MCP(Model Context Protocol)는 Anthropic과 같은 모델을 사용할 수 있도록 하는 개방형 표준입니다. 클로드 및 개발자 도구와 같은 클로드 코드 안전하고 표준화된 방식으로 외부 도구, 데이터 소스 및 프롬프트를 호출합니다.

이 가이드에서는 처음부터 직접 MCP 서버를 구축하는 방법을 안내합니다. 이를 통해 Claude Code가 사용자 지정 기능에 액세스하고 기본 제공 기능을 훨씬 뛰어넘어 기능을 크게 확장할 수 있습니다.

모델 컨텍스트 프로토콜(MCP)이란 무엇입니까?

MCP(Model Context Protocol)는 개방형 사양 언어 모델 클라이언트(예: Claude, Claude Code 또는 기타 LLM 프런트엔드)가 도구 서버 및 데이터 소스에 연결하는 방식을 표준화하도록 설계되었습니다. MCP는 "LLM용 USB-C 포트"라고 생각하면 됩니다. MCP는 전송/JSON-RPC 스키마와 서버가 다음 세 가지 기능을 게시하는 일반적인 방식을 정의합니다.

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

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

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의 솔루션입니다. MCP 서버를 통해 내부 도구(소스 검색, CI 러너, 티켓 시스템, 프라이빗 레지스트리)를 공개하면 Claude Code에서 이를 호출할 수 있습니다. 일류 도구 내부 코딩 대화와 에이전트 흐름.

Claude Code를 MCP 서버와 통합하면 코딩 에이전트에 실용적이고 생산에 적합한 기능이 제공됩니다.

1. 모델을 보자 행동 실제 시스템에서

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

2. 대용량 데이터 및 특수 논리 오프로드

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

3. 보안 및 거버넌스

MCP는 서버 계층에서 액세스 제어 및 감사를 중앙 집중화하여 조직이 승인된 서버를 허용 목록에 추가하고, 사용 가능한 도구를 제어하고, 출력을 제한할 수 있도록 지원합니다. Claude Code는 엔터프라이즈 MCP 구성 및 범위별 동의도 지원합니다.

4. 재사용성과 생태계

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

시작하기 전에 무엇이 필요합니까?

최소 요건

개발 머신 Python 3.10 이상 (예시에서는 Python을 사용합니다.) MCP SDK는 Node.js나 다른 언어도 지원합니다.
uv (Astral의 도구) 또는 MCP stdio 서버를 실행하기 위한 동등한 러너(MCP 튜토리얼에서는 사용) uv). 설치 단계는 아래와 같습니다.
Claude Code를 설치했거나 Claude 클라이언트(데스크톱 또는 CLI)에 액세스하여 서버를 등록하고 테스트하세요. 또는 MCP 지원 클라이언트도 가능합니다. Claude Code는 HTTP, SSE 및 로컬 stdio 서버를 지원합니다.
보안 참고 사항: 팀이나 기업 설정에서 Claude Code에 신뢰할 수 있는 MCP 서버만 추가하세요. MCP는 서버에 민감한 데이터에 대한 접근 권한을 부여하며, 서버에서 악성 콘텐츠를 반환하는 경우 즉각적인 주입 위험이 존재합니다.

Claude Code CLI를 설치하고 확인하는 방법

이것은 클로드 코드 설치 및 사용 가이드.

1) 간략한 요약 - 권장되는 설치 방법

사용 네이티브 설치 프로그램 (권장) 또는 macOS/Linux의 Homebrew를 사용합니다. 노드 기반 설치가 필요한 경우 NPM을 사용할 수 있습니다. Windows에서는 PowerShell/CMD 설치 프로그램이 제공됩니다. 출처: 공식 Claude Code 문서 및 GitHub.

2) 전제조건

macOS 10.15+, Ubuntu 20.04+/Debian 10+ 또는 Windows 10+(Windows에서는 WSL 권장).
노드.js 18+ 필수만 NPM 설치 방법에 대한 내용입니다.

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

네이티브(권장 - 노드 종속성 없음), 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 전역 설치(권한/보안 문제)에 대해 경고합니다. 권한 오류가 발생하면 다음을 사용하세요. nvm 또는 sudo를 사용하는 대신 npm 글로벌 접두사를 수정하세요.

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 or ~/.nvm/.../bin/claude) and claude --version semver와 유사한 문자열을 출력합니다. docs와 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

당신이 사용할 수 코멧APIClaude Code를 사용하려면 API 키가 필요합니다. 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 검사관 또는 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 서버를 빠르게 구축하는 방법은 무엇입니까?

빠른 체크리스트

서버를 시작합니다(스트리밍 가능한 HTTP 권장): node server.ts or uvicorn server:app.
개발 컴퓨터에서 다음 중 하나를 수행합니다.

MCP 검사관 검증하다 (npx @modelcontextprotocol/inspector)을 확인하고 tools/list 및 resources/list, 또는
Claude Code에 서버를 추가합니다. claude mcp add --transport http <name> http://<host>:<port>/mcp (또는 클라이언트가 원격 MCP를 지원하는 경우 웹 UI 흐름을 따르세요).

원격 MCP(별도의 클라이언트 없음)에 Anthropic의 메시지 API 커넥터를 사용하려는 경우 Claude 문서를 읽어보세요. 베타 헤더가 필요할 수 있습니다(정확한 헤더와 현재 지원 상태는 문서에서 확인하세요).

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

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

예제 1: TypeScript + Express(스트리밍 가능 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 빠른 시작에서 가져온 것으로, 도구와 리소스를 등록한 다음 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

검사관에게 연락하세요:

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

Python SDK 예제와 FastMCP 유틸리티를 사용하면 간편하게 등록할 수 있습니다. @mcp.tool() 및 @mcp.resource() LLM이 발견하고 호출할 수 있는 장식된 함수입니다.

클로드 코드는 실제로 도구를 어떻게 호출합니까?

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

어떤 테스트 및 디버깅 도구를 사용해야 합니까?

MCP 검사관

The MCP 검사관 MCP 서버 테스트를 위한 공식 비주얼 개발자 도구입니다. 서버(stdio, SSE 또는 streamable-HTTP)에 연결하고, 도구를 나열하고, 수동으로 호출하고, JSON-RPC 메시지의 수명 주기를 검사할 수 있어 개발 과정에서 매우 유용합니다. 다음을 통해 시작하세요. npx @modelcontextprotocol/inspector.

로컬 테스트 대 원격 테스트

로컬(stdio) — 데스크톱 앱과 오프라인 디버깅을 위한 빠른 반복 주기.
스트리밍 가능한 HTTP — Inspector로 테스트하거나 Claude Code에 연결하세요. claude mcp add 원격 테스트를 위해 메시지 API의 CLI 또는 MCP 커넥터를 사용하세요. 서버에 필요한 모든 인증 헤더를 제공해야 합니다.

결론

MCP는 최신 LLM과 실제로 데이터를 보관하고 작업을 수행하는 시스템을 연결하는 실질적인 다리 역할을 합니다. 코드 워크플로의 경우, Claude Code를 MCP 서버와 통합하면 모델에 저장소, CI, 이슈 트래커 및 사용자 지정 도구에 대한 체계적이고 감사 가능한 접근 권한을 부여하여 더욱 정밀한 자동화와 안전한 부작용을 구현할 수 있습니다. TypeScript 및 Python 공식 SDK, 원격 호스팅을 위한 Streamable HTTP, 그리고 MCP Inspector와 같은 도구를 사용하면 몇 분 만에 최소한의 서버를 구축하고 프로덕션 배포를 위한 반복 작업을 수행할 수 있습니다.

개발자는 액세스할 수 있습니다 클로드 소네 4.5 API 및 클로드 오푸스 4.1 API CometAPI를 통한 등 최신 모델 버전 공식 웹사이트에서 항상 업데이트됩니다. 시작하려면 모델의 기능을 살펴보세요. 운동장 그리고 상담하십시오 API 가이드 자세한 내용은 CometAPI를 참조하세요. 접속하기 전에 CometAPI에 로그인하고 API 키를 발급받았는지 확인하세요. 코멧API 공식 가격보다 훨씬 낮은 가격을 제공하여 통합을 돕습니다.

출발 준비 되셨나요?→ 지금 CometAPI에 가입하세요 !

AI에 대한 더 많은 팁, 가이드 및 뉴스를 알고 싶다면 저희를 팔로우하세요. VK, X 및 디스코드!

Claude Code를 위한 MCP 서버 만들기 - 실용적이고 단계별 가이드

모델 컨텍스트 프로토콜(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(스트리밍 가능 HTTP)

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

클로드 코드는 실제로 도구를 어떻게 호출합니까?

어떤 테스트 및 디버깅 도구를 사용해야 합니까?

MCP 검사관

로컬 테스트 대 원격 테스트

결론

더 보기

하나의 API로 500개 이상의 모델

Claude Code를 위한 MCP 서버 만들기 - 실용적이고 단계별 가이드

모델 컨텍스트 프로토콜(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(스트리밍 가능 HTTP)

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

클로드 코드는 실제로 도구를 어떻게 호출합니까?

어떤 테스트 및 디버깅 도구를 사용해야 합니까?

MCP 검사관

로컬 테스트 대 원격 테스트

결론

더 보기

하나의 API로 500개 이상의 모델

a) `claude doctor`,달리다: