Claude Code용 MCP 서버 만들기 — 실용적인, 최신 단계별 가이드 - CometAPI

Model Context Protocol(MCP)는 Anthropic의 Claude 같은 모델과 Claude Code 같은 개발자 도구가 외部 도구, 데이터 소스, 프롬프트를 안전하고 표준화된 방식으로 호출할 수 있게 해주는 오픈 표준입니다.

이 가이드는 처음부터 직접 MCP 서버를 구축하는 과정을 안내하여 Claude Code가 사용자 정의 기능에 접근할 수 있도록 하고, 기본 기능을 훨씬 넘어 기능을 대폭 확장할 수 있게 합니다.

Model Context Protocol(MCP)란 무엇인가요?

MCP(Model Context Protocol)는 언어 모델 클라이언트(예: Claude, Claude Code, 기타 LLM 프런트엔드)가 도구 서버와 데이터 소스에 연결하는 방식을 표준화하기 위해 설계된 오픈 스펙입니다. MCP를 “LLM용 USB-C 포트”로 생각해 보세요. 전송/JSON-RPC 스키마를 정의하고, 서버가 다음 세 가지 유형의 기능을 게시하는 공통 방식을 제공합니다:

리소스 — 클라이언트가 읽을 수 있는 파일형 또는 문서 데이터(예: 데이터베이스 행, 텍스트 파일, JSON 페이로드).
도구 — 모델이 호스트에 실행을 요청할 수 있는 호출 가능한 함수(사용자 승인 필요).
프롬프트 — 모델/클라이언트가 호출할 수 있는 재사용 가능한 프롬프트 템플릿 또는 워크플로.

MCP는 여러 전송 방식을 지원합니다(stdio, HTTP, SSE). 또한 스키마, SDK, 예제 서버를 제공하므로 와이어 포맷을 직접 만들 필요가 없습니다. 프로토콜과 SDK는 공개적으로 유지 관리되며, 튜토리얼과 예제 서버 갤러리가 제공되어 도입을 가속화합니다.

MCP는 어떻게 설계되어 있나요?

MCP의 아키텍처는 의도적으로 단순하고 모듈식입니다. 핵심 구성 요소는 MCP 서버, MCP 클라이언트, 그리고 이들 사이에서 JSON-RPC로 프레이밍된 메시지를 운반하는 전송 계층입니다. Claude Code(또는 다른 MCP 클라이언트)용 서버를 빌드할 때 상호작용하게 될 주요 구성 요소는 다음과 같습니다.

서버, 클라이언트, 그리고 프로토콜

MCP 서버 — 도구, 리소스, 프롬프트를 게시하는 서비스입니다. 도구는 부작용을 수행하거나 데이터를 가져올 수 있고, 리소스는 읽기 전용 콘텐츠를 표면화하며, 프롬프트는 클라이언트가 모델에 샘플링을 요청할 수 있는 재사용 가능한 템플릿입니다.
MCP 클라이언트(호스트) — 일반적으로 LLM 호스트의 일부입니다(예: Claude Code, VS Code 플러그인, 브라우저 클라이언트). 사용 가능한 서버를 검색하고, 도구 설명을 모델에 제시하며, 모델이 시작한 호출을 서버로 라우팅합니다.
프로토콜 — 메시지는 JSON-RPC로 인코딩됩니다. 스펙은 라이프사이클 이벤트, 도구 검색, 호출, 완성/샘플링, 그리고 구조화된 결과가 클라이언트와 모델로 반환되는 방식을 정의합니다.

통신 패턴(도구가 사용될 때 일어나는 일)

클라이언트가 사용자의 메시지를 모델에 보냅니다.
모델은 컨텍스트를 분석하고 MCP가 노출한 도구(하나 이상)를 호출하기로 결정합니다.
클라이언트는 선택한 전송 방식을 통해 도구 호출을 MCP 서버로 전달합니다.
서버는 도구를 실행하고 결과를 반환합니다.
모델은 도구 출력을 받아 사용자에게 줄 최종 답변을 구성합니다.

구현 기본 요소

JSON-RPC 메시지는 MCP 스키마를 따릅니다.
도구 정의는 서버의 검색 응답에서 게시되어, 클라이언트가 UI에 표시할 수 있습니다.
리소스는 클라이언트가 @source:path 구문으로 참조합니다(예: @postgres:...). 이를 통해 큰 데이터를 프롬프트에 인라인하지 않고도 외부 콘텐츠를 모델이 참조할 수 있습니다.

왜 Claude Code를 MCP 서버와 통합하나요?

Claude Code는 코드 및 개발자 중심 워크플로(에디터/IDE 통합, 코드 이해 등)에 초점을 맞춘 Anthropic의 제품입니다. 내부 도구(소스 검색, CI 러너, 티켓 시스템, 프라이빗 레지스트리 등)를 MCP 서버를 통해 노출하면 Claude Code가 코딩 대화 및 에이전트 플로 내에서 이를 일급 도구로 호출할 수 있습니다.

Claude Code를 MCP 서버와 통합하면 코딩 에이전트에 실용적이고 프로덕션에 적합한 기능이 열립니다:

1. 모델이 실제 시스템에서 동작하도록 하기

Claude Code는 MCP 서버에 이슈 트래커 쿼리, 데이터베이스 쿼리 실행, 대용량 문서 읽기, GitHub PR 생성 등을 요청할 수 있습니다. 이를 통해 코딩 세션 내에서 엔드투엔드 자동화가 가능합니다. 이는 Claude Code 문서에서 명시적으로 지원되며(예: Postgres, Sentry 쿼리, PR 생성), 예시가 제공됩니다.

2. 대용량 데이터와 특화된 로직을 서버로 위임

모든 데이터 소스를 프롬프트에 임베드하여 토큰을 소모하는 대신, 데이터를 리소스/도구로 게시하세요. 모델은 도구를 호출해 구조화된 응답을 받고 이를 바탕으로 추론합니다. 이렇게 하면 토큰 사용량이 줄고, 서버가 무거운 작업(DB 쿼리, 긴 파일 읽기, 인증)을 처리할 수 있습니다.

3. 보안과 거버넌스

MCP는 서버 계층에서 접근 제어와 감사를 중앙화합니다. 조직은 승인된 서버만 화이트리스트로 관리하고, 사용 가능한 도구를 통제하며, 출력 제한을 설정할 수 있습니다. Claude Code는 엔터프라이즈 MCP 구성과 스코프별 동의도 지원합니다.

4. 재사용성과 생태계

MCP 서버는 클라이언트와 팀 간에 재사용할 수 있습니다. 한 번 구축하면 여러 Claude/LLM 클라이언트가 동일한 서비스를 사용할 수 있고, 구현을 교체하는 것도 가능합니다.

시작 전에 무엇이 필요하나요?

최소 요구 사항

Python 3.10+가 설치된 개발 머신(예제에서는 Python을 사용). 대안으로 Node/기타 언어용 MCP SDK도 지원됩니다.
uv(Astral의 도구) 또는 MCP stdio 서버 실행을 위한 동등한 러너(MCP 튜토리얼은 uv 사용). 설치 단계는 아래에 나와 있습니다.
Claude Code가 설치되어 있거나 Claude 클라이언트(데스크톱 또는 CLI)에 접근할 수 있어야 MCP 서버를 등록/테스트할 수 있습니다. 기타 MCP 호환 클라이언트도 가능합니다. Claude Code는 HTTP, SSE, 로컬 stdio 서버를 지원합니다.
보안 참고: 팀 또는 엔터프라이즈 환경에서 Claude Code에 신뢰할 수 있는 MCP 서버만 추가하세요. MCP는 서버에 민감한 데이터 접근 권한을 부여하며, 서버가 악성 콘텐츠를 반환할 경우 프롬프트 인젝션 위험이 존재합니다.

Claude Code CLI를 설치하고 검증하는 방법

여기는 Claude Code 설치 및 사용 가이드입니다.

1) 빠른 요약 — 권장 설치 방법

네이티브 설치 관리자(권장) 또는 macOS/Linux의 Homebrew를 사용하세요. 필요 시 NPM도 사용할 수 있습니다. Windows는 PowerShell/CMD 설치 관리자를 제공합니다. 출처: 공식 Claude Code 문서 및 GitHub.

2) 사전 준비

macOS 10.15+, Ubuntu 20.04+/Debian 10+, 또는 Windows 10+(Windows에서는 WSL 권장).
NPM 설치 방식을 사용할 경우에만 Node.js 18+가 필요합니다.

3) 설치 명령(하나를 선택)

네이티브(권장 — Node 종속성 없음), macOS / Linux / WSL:

curl -fsSL https://claude.ai/install.sh | bash
# optional: install latest explicitly

curl -fsSL https://claude.ai/install.sh | bash -s latest
# or install a specific version

curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

Windows PowerShell:

irm https://claude.ai/install.ps1 | iex
# or for latest: & (::Create((irm https://claude.ai/install.ps1))) latest

(공식 네이티브 설치 스크립트입니다.)

NPM(Node 기반 전역 설치가 필요한 경우):

# requires Node.js 18+

npm install -g @anthropic-ai/claude-code

sudo npm install -g는 사용하지 마세요 — 전역 설치에 sudo를 사용하는 것은 권장되지 않습니다(권한/보안 이슈). 권한 오류가 발생하면 sudo 대신 nvm을 사용하거나 npm 글로벌 prefix 설정을 수정하세요.

4) 바이너리 설치 확인(기본 점검)

설치 직후 로컬에서 다음을 실행하세요:

# is the command on PATH?

which claude

# version (or -v)

claude --version
# or

claude -v

# help (sanity check)

claude --help

예상: which는 경로를 보여주고(예: /usr/local/bin/claude 또는 ~/.nvm/.../bin/claude), claude --version은 semver 형태의 문자열을 출력합니다. 문서와 README 모두 claude를 기본 CLI 엔트리포인트로 안내합니다.

5) 설치 상태와 구성 검증(권장 점검)

a) `claude doctor` 실행:

claude doctor

내장 진단 도구가 설치 유형, 일반적인 문제(npm 권한 이슈 등), ripgrep 같은 의존성, 수정 제안을 점검합니다. 문서에서는 설치 후 claude doctor 실행을 명시적으로 권장합니다.

b) 스모크 테스트(비대화형) 실행

프로젝트 디렉터리에서:

cd /path/to/your/project
claude -p "Explain this project in 3 sentences"

이 명령은 단일 프롬프트를 전송하고 종료하는 프린트 모드(-p)를 사용합니다. CI 또는 빠른 기능 점검에 유용합니다.

c) 인증 확인(CLI가 Anthropic에 도달 가능한지 확인)

Claude Code는 여러 인증 플로(콘솔 OAuth, API 키, 프로바이더 통합)를 지원합니다. 일반적인 확인 방법:

API 키 사용 시(CI/헤드리스/로컬 환경변수):

export ANTHROPIC_API_KEY="sk-..."
# then

claude auth status
claude auth whoami    # or `claude auth whoami` / `claude whoami` depending on version

CometAPI의 API 키로 Claude Code를 사용할 수 있습니다. CometAPI를 통해 Claude의 API를 사용하면 20% 할인 혜택을 받을 수 있습니다.

콘솔을 통한 OAuth를 사용한 경우 — 다음을 실행:

claude auth status
claude auth whoami

계정/플랜 정보 또는 인증 완료 확인이 표시되어야 합니다.

단계별 환경 준비

아래는 두 가지 일반적인 개발 스택(TypeScript와 Python)을 준비하는 구체적 단계이며, 이어서 모든 것이 정상 작동하는지 빠르게 확인하는 방법을 제공합니다.

H3 — A. TypeScript / Node 설정(가장 빠른 경로)

프로젝트 생성 및 SDK 설치:

mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk express zod
npm install --save-dev typescript tsx @types/node @types/express

server.ts를 만듭니다.(“빠르게 빌드하는 방법” 섹션에서 전체 예제를 제공합니다.)
실행:

npx -y tsx server.ts

로컬에서 MCP Inspector로 테스트하거나 Claude Code에 추가:

npx @modelcontextprotocol/inspector
# or (for Claude Code)

claude mcp add --transport http my-server http://localhost:3000/mcp

(Inspector와 Claude 명령으로 디스커버리 검증 및 도구 호출을 확인할 수 있습니다.)

Claude Code용 MCP 서버를 빠르게 빌드하는 방법은?

빠른 체크리스트

서버를 시작합니다(Streamable HTTP 권장): node server.ts 또는 uvicorn server:app.
개발 머신에서 다음 중 하나를 수행합니다:

MCP Inspector로 검증(npx @modelcontextprotocol/inspector)하고 tools/list와 resources/list를 확인하거나,
Claude Code에 서버를 추가합니다: claude mcp add --transport http <name> http://<host>:<port>/mcp(클라이언트가 원격 MCP를 위한 웹 UI 플로를 지원하는 경우 해당 플로를 따르세요).

원격 MCP용 Anthropic의 Messages API 커넥터를 사용할 계획이라면(별도 클라이언트 없음), Claude 문서를 확인하세요 — 베타 헤더가 필요할 수 있습니다(정확한 헤더와 현재 지원 상태는 문서를 참조).

아래에는 Claude Code(또는 MCP Inspector)에 연결할 수 있는 두 가지 완전하면서도 간결한 서버 예제가 있습니다. TypeScript 예제는 Express + TypeScript SDK를 사용하고, Python 예제는 FastAPI 마운팅을 보여줍니다.

참고: 아래 코드는 공개 SDK 예제를 따르며 명확성을 위해 의도적으로 최소화되어 있습니다. 프로덕션에서는 SDK 기본값 외에 인증, 로깅, 속도 제한, 입력 검증을 추가하세요.

예제 1: TypeScript + Express(Streamable HTTP)

server.ts 생성(완전본):

// server.ts
import express from "express";
import * as z from "zod/v4";
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const server = new McpServer({ name: "claude-code-demo", version: "0.1.0" });

// Register a simple tool: add two numbers
server.registerTool(
  "add",
  {
    title: "Add",
    description: "Add two numbers a and b",
    inputSchema: { a: z.number(), b: z.number() },
    outputSchema: { result: z.number() }
  },
  async ({ a, b }) => {
    const output = { result: a + b };
    return {
      content: ,
      structuredContent: output
    };
  }
);

// Register a resource: greet user (dynamic)
server.registerResource(
  "greeting",
  new ResourceTemplate("greeting://{name}", { list: undefined }),
  { title: "Greeting", description: "Return a greeting for the name" },
  async (uri, params) => {
    return {
      contents: 
    };
  }
);

// Express + Streamable HTTP transport
const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
  // Close transport when connection closes
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

const port = parseInt(process.env.PORT || "3000", 10);
app.listen(port, () => console.log(`MCP server listening: http://localhost:${port}/mcp`));

실행:

npm install
npx -y tsx server.ts

그런 다음 Claude Code에 연결(예):

# Add the remote server to your Claude Code MCP list (local dev)

claude mcp add --transport http my-demo http://localhost:3000/mcp

이 예제는 공식 TypeScript SDK Quick Start를 참고하여 작성되었으며, 도구와 리소스를 등록하고 이를 Streamable HTTP로 노출하는 방법을 보여줍니다.

예제 2: Python + FastAPI(FastMCP + Streamable HTTP)

server.py 생성(완전본):

# server.py

from fastapi import FastAPI
from mcp.server.fastmcp import FastMCP

app = FastAPI()
mcp = FastMCP("claude-python-demo", stateless_http=True)

# tool: simple sum

@mcp.tool()
def add(a: int, b: int) -> dict:
    """Add two integers"""
    return {"result": a + b}

# resource: simple greeting resource template

@mcp.resource("greeting://{name}")
def greeting(name: str):
    return {"contents": }

# mount the streamable-http MCP endpoint (FastMCP exposes an ASGI app)

app.mount("/mcp", mcp.streamable_http_app())

# optional endpoint to demonstrate other API routes

@app.get("/")
async def root():
    return {"status": "OK"}

실행:

uvicorn server:app --reload --port 8000

Inspector로 연결:

npx @modelcontextprotocol/inspector
# In Inspector select Streamable HTTP and enter http://localhost:8000/mcp

Python SDK 예제와 FastMCP 유틸리티를 사용하면 @mcp.tool()과 @mcp.resource() 데코레이터로 LLM이 검색하고 호출할 수 있는 함수를 손쉽게 등록할 수 있습니다.

Claude Code는 실제로 어떻게 여러분의 도구를 호출하나요?

LLM이 도구 사용을 결정하면, 클라이언트가 MCP 서버로 JSON-RPC 호출을 보냅니다. 서버는 요청된 도구를 실행(예: DB 쿼리, 테스트 실행, 외부 API 호출)하고 구조화된 콘텐츠와 표시용 콘텐츠를 반환합니다. 클라이언트(Claude Code)는 구조화된 출력을 모델의 컨텍스트에 포함시켜, 모델이 신뢰할 수 있는 데이터로 계속 추론할 수 있게 합니다. TypeScript SDK는 inputSchema와 outputSchema(zod)를 등록하는 것을 지원하여, 인수와 출력이 검증되고 기계적으로 타입이 지정되도록 합니다.

어떤 테스트 및 디버깅 도구를 사용해야 하나요?

MCP Inspector

MCP Inspector는 MCP 서버 테스트를 위한 공식 시각화 개발 도구입니다. 서버(stdio, SSE, streamable-HTTP)에 연결하고, 도구를 나열하고, 수동으로 호출하며, JSON-RPC 메시지 라이프사이클을 검사할 수 있어 개발에 매우 유용합니다. npx @modelcontextprotocol/inspector로 시작하세요.

로컬 vs 원격 테스트

로컬(stdio) — 데스크톱 앱 및 오프라인 디버깅에 적합한 빠른 반복 주기.
Streamable HTTP — Inspector로 테스트하거나 claude mcp add CLI 또는 Messages API의 MCP 커넥터를 사용해 Claude Code에 연결하여 원격 테스트를 진행합니다. 서버에 필요한 인증 헤더가 있다면 반드시 제공하세요.

결론

MCP는 최신 LLM과 실제로 데이터를 보유하고 작업을 수행하는 시스템 사이를 이어주는 실용적인 다리입니다. 코드 워크플로에서 MCP 서버와 Claude Code를 통합하면, 모델이 저장소, CI, 이슈 트래커, 사용자 정의 도구에 구조화되고 감사 가능한 방식으로 접근할 수 있어 더 정확한 자동화와 더 안전한 부작용 처리가 가능합니다. TypeScript와 Python용 공식 SDK, 원격 호스팅을 위한 Streamable HTTP, 그리고 MCP Inspector 같은 도구를 통해, 몇 분 만에 최소 서버를 구축하고 프로덕션 배포를 향해 반복 개선할 수 있습니다.

개발자는 Claude Sonnet 4.5 API와 Claude Opus 4.1 API 등을 CometAPI를 통해 이용할 수 있습니다. 최신 모델 버전은 항상 공식 웹사이트와 동기화되어 업데이트됩니다. 시작하려면 Playground에서 모델 기능을 탐색하고, 자세한 지침은 API 가이드를 참고하세요. 접근 전에 CometAPI에 로그인하고 API 키를 발급받았는지 확인해 주세요. CometAPI는 통합을 돕기 위해 공식가보다 훨씬 저렴한 가격을 제공합니다.

Ready to Go?→ Sign up for CometAPI today !

AI 관련 팁, 가이드, 소식을 더 알고 싶다면 저희를 팔로우하세요: VK, X, Discord!

Claude Code용 MCP 서버 만들기 — 실용적인, 최신 단계별 가이드

Model Context Protocol(MCP)란 무엇인가요?

MCP는 어떻게 설계되어 있나요?

서버, 클라이언트, 그리고 프로토콜

통신 패턴(도구가 사용될 때 일어나는 일)

구현 기본 요소

왜 Claude Code를 MCP 서버와 통합하나요?

1. 모델이 실제 시스템에서 동작하도록 하기

2. 대용량 데이터와 특화된 로직을 서버로 위임

3. 보안과 거버넌스

4. 재사용성과 생태계

시작 전에 무엇이 필요하나요?

최소 요구 사항

Claude Code CLI를 설치하고 검증하는 방법

1) 빠른 요약 — 권장 설치 방법

2) 사전 준비

3) 설치 명령(하나를 선택)

4) 바이너리 설치 확인(기본 점검)

5) 설치 상태와 구성 검증(권장 점검)

a) `claude doctor` 실행:

b) 스모크 테스트(비대화형) 실행

c) 인증 확인(CLI가 Anthropic에 도달 가능한지 확인)

단계별 환경 준비

H3 — A. TypeScript / Node 설정(가장 빠른 경로)

Claude Code용 MCP 서버를 빠르게 빌드하는 방법은?

빠른 체크리스트

예제 1: TypeScript + Express(Streamable HTTP)

예제 2: Python + FastAPI(FastMCP + Streamable HTTP)

Claude Code는 실제로 어떻게 여러분의 도구를 호출하나요?

어떤 테스트 및 디버깅 도구를 사용해야 하나요?

MCP Inspector

로컬 vs 원격 테스트

결론

AI 개발 비용을 20% 절감할 준비가 되셨나요?

더 보기

Claude Code용 MCP 서버 만들기 — 실용적인, 최신 단계별 가이드

Model Context Protocol(MCP)란 무엇인가요?

MCP는 어떻게 설계되어 있나요?

서버, 클라이언트, 그리고 프로토콜

통신 패턴(도구가 사용될 때 일어나는 일)

구현 기본 요소

왜 Claude Code를 MCP 서버와 통합하나요?

1. 모델이 실제 시스템에서 동작하도록 하기

2. 대용량 데이터와 특화된 로직을 서버로 위임

3. 보안과 거버넌스

4. 재사용성과 생태계

시작 전에 무엇이 필요하나요?

최소 요구 사항

Claude Code CLI를 설치하고 검증하는 방법

1) 빠른 요약 — 권장 설치 방법

2) 사전 준비

3) 설치 명령(하나를 선택)

4) 바이너리 설치 확인(기본 점검)

5) 설치 상태와 구성 검증(권장 점검)

a) claude doctor 실행:

b) 스모크 테스트(비대화형) 실행

c) 인증 확인(CLI가 Anthropic에 도달 가능한지 확인)

단계별 환경 준비

H3 — A. TypeScript / Node 설정(가장 빠른 경로)

Claude Code용 MCP 서버를 빠르게 빌드하는 방법은?

빠른 체크리스트

예제 1: TypeScript + Express(Streamable HTTP)

예제 2: Python + FastAPI(FastMCP + Streamable HTTP)

Claude Code는 실제로 어떻게 여러분의 도구를 호출하나요?

어떤 테스트 및 디버깅 도구를 사용해야 하나요?

MCP Inspector

로컬 vs 원격 테스트

결론

AI 개발 비용을 20% 절감할 준비가 되셨나요?

더 보기

a) `claude doctor` 실행: