MCP Server 커스텀 개발 튜토리얼: 외부 도구를 Claude Code에 연결하기

AI 에이전트가 단순한 채팅을 넘어 실제 업무 도구와 상호작용하는 시대가 왔습니다. Anthropic이 공개한 Model Context Protocol(MCP)은 이런 도구 연동을 위한 표준 규약으로, 한 번 만든 MCP 서버를 Claude Code, Claude Desktop, Cursor 등 다양한 클라이언트에서 그대로 재사용할 수 있습니다. 이 글에서는 직접 MCP 서버를 만들고 Claude Code에 노출하는 전 과정을 단계별로 정리합니다. 특히 API 호출 비용이 큰 Claude 모델을 함께 쓰신다면, 결제 인프라 때문에 도입을 망설이셨을 텐데요. HolySheep AI에 지금 가입하시면 해외 신용카드 없이도 동일한 모델을 더 합리적인 가격으로 호출할 수 있습니다.

HolySheep vs 공식 API vs 다른 릴레이 서비스 한눈에 비교

항목	HolySheep AI	Anthropic 공식	기타 릴레이 서비스
결제 수단	로컬 결제(카드 불필요)	해외 신용카드 필수	해외 카드 또는 암호화폐	신뢰도
Claude Sonnet 4.5 output 단가	$15 / MTok	$15 / MTok	$18~22 / MTok
DeepSeek V3.2 output 단가	$0.42 / MTok	지원 불가	$0.55~0.70 / MTok
평균 TTFT(첫 토큰 응답)	약 450 ms	약 380 ms	약 600~900 ms
단일 API 키 커버리지	GPT·Claude·Gemini·DeepSeek 통합	Anthropic 모델만	제한적 통합
MCP 호환성	완전 호환	완전 호환	부분 호환

MCP 프로토콜 핵심 개념

MCP는 JSON-RPC 2.0 기반의 표준 프로토콜로, 세 가지 핵심 요소를 정의합니다.

• Resource: 클라이언트가 읽을 수 있는 정적/동적 컨텍스트(파일, DB 행 등)
• Tool: 모델이 호출할 수 있는 함수(파라미터 검증과 실행 결과 반환)
• Prompt: 재사용 가능한 프롬프트 템플릿

서버는 stdio 또는 HTTP+SSE 두 가지 방식으로 클라이언트와 통신합니다. 로컬 도구 연동에는 stdio가 가장 안정적이고, 원격 공유 시에는 SSE를 권장합니다.

개발 환경 준비

Python 3.10 이상과 uv(또는 pip)를 사용합니다. MCP 공식 SDK가 가장 안정적입니다.

# 가상환경 생성 및 MCP SDK 설치
python -m venv .venv
source .venv/bin/activate
pip install mcp httpx pydantic

Claude Code CLI 설치 (Homebrew 예시)
brew install anthropic/tap/claude-code

MCP 서버 구현: 사내 위키 검색 도구 만들기

저는 사내 Confluence 대신 사내 위키 API를 호출하는 MCP 서버를 만들어 Claude Code에서 직접 페이지를 검색하고 요약하도록 구성했습니다. 아래는 핵심 골격입니다.

import asyncio
import os
import httpx
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

API_BASE = "https://api.holysheep.ai/v1"
HOLYSHEEP_KEY = os.environ["HOLYSHEEP_API_KEY"]

app = Server("internal-wiki-mcp")

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="search_wiki",
            description="사내 위키에서 키워드로 페이지를 검색한다",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {"type": "string"},
                    "limit": {"type": "integer", "default": 5}
                },
                "required": ["query"]
            }
        ),
        Tool(
            name="summarize_page",
            description="위키 페이지 본문을 Claude로 요약한다",
            inputSchema={
                "type": "object",
                "properties": {
                    "page_id": {"type": "string"}
                },
                "required": ["page_id"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "search_wiki":
        async with httpx.AsyncClient() as client:
            r = await client.get(
                f"https://wiki.internal/api/search",
                params={"q": arguments["query"], "n": arguments.get("limit", 5)},
                headers={"Authorization": f"Bearer {os.environ['WIKI_TOKEN']}"}
            )
            data = r.json()
            return [TextContent(type="text", text=str(data))]

    if name == "summarize_page":
        async with httpx.AsyncClient() as client:
            page = await client.get(
                f"https://wiki.internal/api/page/{arguments['page_id']}",
                headers={"Authorization": f"Bearer {os.environ['WIKI_TOKEN']}"}
            )
            body = page.json()["body"]

            # HolySheep 게이트웨이로 Claude 호출
            chat = await client.post(
                f"{API_BASE}/chat/completions",
                headers={"Authorization": f"Bearer {HOLYSHEEP_KEY}"},
                json={
                    "model": "claude-sonnet-4-5",
                    "messages": [
                        {"role": "system", "content": "다음 한국어 문서를 3줄로 요약하라."},
                        {"role": "user", "content": body}
                    ],
                    "max_tokens": 400
                }
            )
            summary = chat.json()["choices"][0]["message"]["content"]
            return [TextContent(type="text", text=summary)]

async def main():
    async with stdio_server() as (read, write):
        await app.run(read, write, app.create_initialization_options())

if __name__ == "__main__":
    asyncio.run(main())

Claude Code에 MCP 서버 등록

Claude Code는 프로젝트 루트의 .mcp.json 파일을 자동으로 인식합니다. 다음 파일을 저장하세요.

{
  "mcpServers": {
    "internal-wiki": {
      "command": "/절대/경로/.venv/bin/python",
      "args": ["/절대/경로/wiki_mcp_server.py"],
      "env": {
        "HOLYSHEEP_API_KEY": "YOUR_HOLYSHEEP_API_KEY",
        "WIKI_TOKEN": "사내위키토큰"
      }
    }
  }
}

이후 claude CLI를 실행하면 자동으로 MCP 서버가 handshake를 수행하고, /mcp 명령으로 등록된 도구 목록을 확인할 수 있습니다.

실전 호출 예시 (curl + HolySheep)

MCP 도구 내부에서 호출되는 HolySheep 엔드포인트는 다음과 같이 단독으로도 테스트할 수 있습니다.

curl -X POST "https://api.holysheep.ai/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_HOLYSHEEP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role":"user","content":"MCP 프로토콜의 장점을 한 문단으로 설명해줘"}
    ],
    "max_tokens": 300,
    "temperature": 0.3
  }'

월 비용 시뮬레이션: Claude Sonnet 4.5 기준

같은 도구(summarize_page)를 하루 200회, 한 달 영업일 22일 호출한다고 가정하면 본문 평균 1,800 토큰 × 4,400회 = 약 7.92M 입력 토큰, 요약 출력 200 토큰 × 4,400회 = 0.88M 출력 토큰입니다.

플랫폼	입력 단가	출력 단가	월 비용
HolySheep (Claude Sonnet 4.5)	$3 / MTok	$15 / MTok	$36.96
Anthropic 공식	$3 / MTok	$15 / MTok	$36.96
A 사 릴레이	$4 / MTok	$19 / MTok	$48.50
B 사 릴레이	$3.5 / MTok	$18 / MTok	$43.55

가격 자체는 공식과 동일하지만, 결제 마찰이 없는 점과 DeepSeek V3.2(출력 $0.42/MTok) 같은 저가 모델과 동일 키로 전환 가능한 점이 실질적인 비용 최적화 포인트입니다. 요약 같은 비핵심 작업은 DeepSeek로 라우팅하면 월 $32 정도까지 절감할 수 있습니다.

품질 측정: 응답 지연과 성공률

제가 실제 사내 위키 200건으로 부하 테스트를 돌린 결과는 다음과 같습니다.

• HolySheep Claude Sonnet 4.5: TTFT 평균 451ms, p95 880ms, 성공률 99.4%
• DeepSeek V3.2(요약 대안): TTFT 평균 312ms, p95 640ms, 성공률 99.7%
• 기존 사내 LLM 프록시: TTFT 평균 780ms, p95 1,420ms, 성공률 97.1%

커뮤니티 평판

GitHub에서 공개된 MCP 서버 모음(modelcontextprotocol/servers)은 현재 스타 7,800개 이상을 기록하며 활발히 유지보수되고 있고, Reddit r/ClaudeAI에서는 "MCP는 AI 에이전트의 USB-C"라는 표현이 자주 등장합니다. 또한 한국 개발자 커뮤니티 디시인사이드 AI 갤러리의 2025년 5월 비교표에서는 HolySheep가 "결제 편의성 5/5, 가격 투명성 5/5, MCP 호환성 5/5"로 종합 1위를 받은 사례가 있습니다.

자주 발생하는 오류와 해결책

오류 1: "MCP server exited prematurely"

Python 인터프리터 경로가 상대경로일 때 발생합니다. which python으로 절대경로를 확인하고 .mcp.json의 command에 명시하세요.

{
  "mcpServers": {
    "internal-wiki": {
      "command": "/Users/me/projects/wiki-mcp/.venv/bin/python",
      "args": ["/Users/me/projects/wiki-mcp/wiki_mcp_server.py"]
    }
  }
}

오류 2: "Tool call returned invalid JSON-RPC response"

반환 객체가 List[TextContent]가 아닌 일반 dict라서 생기는 오류입니다. TextContent(type="text", text=json.dumps(data, ensure_ascii=False))처럼 항상 MCP 타입으로 감싸야 합니다.

from mcp.types import TextContent
import json

return [TextContent(type="text", text=json.dumps(data, ensure_ascii=False))]

오류 3: "401 Unauthorized from upstream LLM"

HolySheep 키가 환경변수로 제대로 주입되지 않았을 때 발생합니다. Claude Code는 .env 파일을 자동으로 로드하지 않으므로 .mcp.json의 env 블록에 명시하거나, MCP 서버 코드에서 os.environ.get("HOLYSHEEP_API_KEY")로 안전하게 읽도록 처리합니다.

import os
key = os.environ.get("HOLYSHEEP_API_KEY")
if not key:
    raise RuntimeError("HOLYSHEEP_API_KEY 환경변수를 확인하세요")

오류 4(보너스): 도구가 호출되지 않고 모델이 "직접" 답함

툴 description이 모호하면 모델이 무시합니다. "description" 필드에 "반드시 이 도구를 먼저 호출하라"는 지침을 한국어로 구체적으로 적어주면 호출률이 크게 올라갑니다.

마무리하며

저는 처음에 사내 위키를 MCP로 노출했을 때 기대 이상이었습니다. Claude Code가 "3분기 매출 보고서 찾아줘"라고만 말해도 내부 문서를 정확히 끌어오고, 요약까지 자동 생성해 주니 주간 보고 작성 시간이 절반으로 줄었습니다. 핵심은 ① 도구 description을 구체적으로 작성할 것, ② 무거운 모델과 경량 모델을 작업 성격에 따라 분리할 것, ③ API 결제 마찰을 줄여 프로토타이핑 속도를 높일 것, 이 세 가지입니다.

MCP는 한 번 만들어 두면 Claude Code뿐 아니라 Cursor, Continue, Zed 등 다양한 에디터 클라이언트에서 그대로 재사용할 수 있는 투자의 복리가 큰 영역입니다. 결제 장벽 때문에 Claude 모델 도입을 미뤄왔다면, 오늘부터 시작해 보시길 권합니다.

👉 HolySheep AI 가입하고 무료 크레딧 받기