Claude × Model Context Protocol (MCP) 연동 개발 가이드

Claude 모델이 MCP (Model Context Protocol) 클라이언트로 사용되는 상황을 전제로,
FastAPI 기반 MCP-compatible 서버를 포함한 전체 구조와 샘플 코드를 Claude와 연동 가능한 형식으로 다시 정리

---

🧠 Claude × Model Context Protocol (MCP) 연동 개발 가이드

📌 핵심 요약

LLM Client	Claude (Anthropic)
MCP Server	FastAPI 앱 (JSON-RPC 2.0)
Tools	fetch_github_issues, etc.
Transport	HTTP (or WebSocket)
Format	JSON-RPC v2

Claude는 tool.list, tool.call, resource.list 등의 메시지를 통해 외부 서버에 기능 요청을 합니다.
우리는 그 요청을 처리하는 MCP-compatible 서버를 FastAPI로 구성합니다.

---

🧱 아키텍처 개요

┌────────────┐                 ┌──────────────────────┐
│  Claude AI │ ← JSON-RPC →   │ FastAPI MCP Server   │
│  (LLM)     │                 │ • tool.list          │
└────────────┘                 │ • tool.call          │
        ▲                      │ • resource.list      │
        │                      └──────────────────────┘
        │                                   │
        ▼                                   ▼
 [TOOL] fetch_github_issues()     [RESOURCE] docs / examples

---

✅ Claude와 연동 가능한 MCP Server 개발

📂 프로젝트 구조

mcp_server/
├── main.py
├── tools/tool_registry.py
└── models/schemas.py

---

🔹 main.py – MCP 엔드포인트

from fastapi import FastAPI, Request
from tools.tool_registry import TOOL_REGISTRY

app = FastAPI()

@app.post("/")
async def mcp_entrypoint(req: Request):
    data = await req.json()
    method = data.get("method")
    params = data.get("params", {})
    req_id = data.get("id")

    if method == "tool.list":
        return {
            "jsonrpc": "2.0",
            "result": [tool["name"] for tool in TOOL_REGISTRY],
            "id": req_id
        }

    elif method == "tool.call":
        tool_name = params.get("tool")
        arguments = params.get("arguments", {})
        tool = next((t for t in TOOL_REGISTRY if t["name"] == tool_name), None)

        if not tool:
            return {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Tool not found"}, "id": req_id}

        try:
            result = await tool["handler"](**arguments)
            return {"jsonrpc": "2.0", "result": result, "id": req_id}
        except Exception as e:
            return {"jsonrpc": "2.0", "error": {"code": -32000, "message": str(e)}, "id": req_id}

    return {"jsonrpc": "2.0", "error": {"code": -32601, "message": "Method not supported"}, "id": req_id}

---

반응형

🔹 tools/tool_registry.py – Claude가 호출할 툴 등록

python

 

import httpx

async def fetch_github_issues(query: str):
    async with httpx.AsyncClient() as client:
        url = f"https://api.github.com/search/issues?q={query}"
        headers = {"Accept": "application/vnd.github+json"}
        resp = await client.get(url, headers=headers)
        return resp.json()

TOOL_REGISTRY = [
    {
        "name": "fetch_github_issues",
        "description": "GitHub 이슈를 키워드로 검색",
        "parameters": {
            "type": "object",
            "properties": {
                "query": { "type": "string" }
            },
            "required": ["query"]
        },
        "handler": fetch_github_issues
    }
]

---

🔸 Claude에서 tool.call 사용 예시

Claude Prompt (in natural language):

Call the fetch_github_issues tool with the query repo:openai/openai-python bug.

Claude가 MCP 요청을 자동 생성합니다:

{
  "jsonrpc": "2.0",
  "method": "tool.call",
  "params": {
    "tool": "fetch_github_issues",
    "arguments": {
      "query": "repo:openai/openai-python bug"
    }
  },
  "id": "req-001"
}

반응형

반응형

---

🔐 추가: 인증 및 제한

Claude에서 안전하게 MCP를 쓰기 위한 필수 보안 추가:

• API Key Header 검사:
•  
   
• python

api_key = req.headers.get("X-API-Key")
if api_key != os.getenv("MCP_API_KEY"):
    return {"jsonrpc": "2.0", "error": {"code": 403, "message": "Invalid API Key"}, "id": req_id}

• Rate Limit, Logging, Audit도 필요한 경우 추가 가능합니다.

---

🚀 확장 가능 항목

기능방법

resource.list, .get	문서 목록 및 상세 반환 구현 (PDF/Markdown 등)
Claude Prompt 연동	프롬프트 템플릿을 MCP 서버에서 서빙
Claude + Tool 연속 호출	tool.call 결과 → 다음 prompt 자동 연계

---

📦 Dockerfile & Run

Dockerfile

dockerfile

 

FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install fastapi uvicorn httpx
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]

bash

 

docker build -t mcp-server .
docker run -p 8080:8080 mcp-server

---

📌 MCP 등록을 위한 Claude 클라이언트 설정 (예시)

json

 

{
  "tools": [
    {
      "url": "https://your-server.com/",
      "name": "fetch_github_issues"
    }
  ]
}