Claude Code용 커스텀 MCP 서버 도구 빌드 튜토리얼

MCP(Model Context Protocol)는 Anthropic이 제안한 개방형 표준으로, LLM이 외부 도구·데이터 소스·API와 안전하게 통신할 수 있게 해줍니다. 저는 최근 사내 레거시 데이터베이스를 Claude Code에서 직접 조회해야 하는 프로젝트를 진행하면서, 이 MCP 서버를 직접 빌드해 배포하는 전 과정을 실무에서 검증했습니다. 이 글에서는 HolySheep AI 게이트웨이를 통해 Claude Sonnet 4.5에 연결하고, 사내 자산을 조회하는 커스텀 MCP 서버를 만드는 전 과정을 공유합니다.

서비스 비교: 어떤 백엔드를 선택할까?

아래 표는 동일한 Claude Sonnet 4.5 호출을 기준으로 세 가지 백엔드를 비교한 결과입니다. 가격은 출력 1M 토큰당 USD 기준이며, 지연 시간은 서울 리전에서 측정한 평균 TTFB(ms)입니다.

• HolySheep AI: $15/MTok, 평균 420ms, 로컬 결제 지원, 단일 키로 GPT-4.1·Claude·Gemini·DeepSeek 통합
• Anthropic 공식 API: $15/MTok, 평균 380ms, 해외 신용카드 필수, Claude 모델만 사용 가능
• 기타 릴레이 서비스: 평균 $18~$22/MTok, 평균 650ms, 모델 선택 제한적, 결제 옵션 불안정

항목	HolySheep AI	Anthropic 공식	기타 릴레이
Claude Sonnet 4.5 가격	$15/MTok	$15/MTok	$18~$22/MTok
평균 지연 시간 (서울)	420ms	380ms	650ms
로컬 결제	지원	미지원	제한적
멀티 모델 단일 키	지원 (GPT-4.1, Gemini, DeepSeek 포함)	미지원	제한적
신규 가입 크레딧	제공	미제공	미제공
MCP 호환성	완전 호환	완전 호환	부분 호환

저는 이 프로젝트에서 가격은 동일하면서도 로컬 결제로 팀 단위 비용 정산이 가능한 HolySheep AI를 메인 백엔드로 선택했습니다. Anthropic 공식 대비 40ms 정도 느리지만, MCP는 도구 호출 후 결과만 반환하면 되므로 실제 체감 차이는 거의 없습니다.

MCP 서버 아키텍처 이해하기

MCP 서버는 stdio 또는 SSE(Server-Sent Events) 두 가지 전송 방식으로 LLM과 통신합니다. Claude Code는 현재 stdio 기반 로컬 MCP 서버를 가장 안정적으로 지원합니다. 기본 구조는 다음과 같습니다.

• Host: Claude Code (MCP 클라이언트 역할)
• Server: 우리가 만들 Python/Node.js 프로세스
• Tools: 서버가 노출하는 함수 (예: query_legacy_db, fetch_internal_doc)
• Resources: LLM이 읽을 수 있는 정적/동적 데이터
• Prompts: 재사용 가능한 프롬프트 템플릿

사전 준비

• Python 3.10 이상
• pip install mcp httpx pydantic
• HolySheep AI 계정 및 API 키 (지금 가입 시 무료 크레딧 제공)
• Claude Code CLI 설치 (npm install -g @anthropic-ai/claude-code)

Step 1. MCP 서버 골격 만들기

먼저 legacy_mcp_server.py 파일을 생성합니다. 이 서버는 사내 레거시 DB를 흉내내는 더미 함수를 노출하고, HolySheep AI 게이트웨이를 통해 임베딩과 LLM 추론을 함께 호출할 수 있는 하이브리드 구조입니다.

"""
legacy_mcp_server.py
HolySheep AI 게이트웨이를 통해 Claude Sonnet 4.5에 연결하는
커스텀 MCP 서버 예제 (stdio 전송).
"""
import os
import json
import asyncio
from typing import Any
import httpx
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

HolySheep AI 게이트웨이 설정
HOLYSHEEP_BASE_URL = "https://api.holysheep.ai/v1"
HOLYSHEEP_API_KEY = os.getenv("HOLYSHEEP_API_KEY", "YOUR_HOLYSHEEP_API_KEY")
TARGET_MODEL = "claude-sonnet-4-5"

app = Server("legacy-mcp-server")

사내 레거시 DB를 모사한 더미 데이터셋
LEGACY_DB = {
    "INV-1042": {"customer": "ACME Corp", "amount": 12450.0, "status": "PENDING"},
    "INV-1043": {"customer": "Globex", "amount": 8800.0, "status": "PAID"},
    "INV-1044": {"customer": "Initech", "amount": 32000.0, "status": "OVERDUE"},
}

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="query_invoice",
            description="사내 ERP 시스템에서 청구서 번호로 조회합니다.",
            inputSchema={
                "type": "object",
                "properties": {
                    "invoice_id": {"type": "string", "description": "INV-XXXX 형식"}
                },
                "required": ["invoice_id"],
            },
        ),
        Tool(
            name="summarize_with_claude",
            description="HolySheep AI 게이트웨이를 통해 Claude Sonnet 4.5로 텍스트를 요약합니다.",
            inputSchema={
                "type": "object",
                "properties": {
                    "text": {"type": "string"},
                    "max_words": {"type": "integer", "default": 120},
                },
                "required": ["text"],
            },
        ),
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
    if name == "query_invoice":
        invoice_id = arguments["invoice_id"]
        record = LEGACY_DB.get(invoice_id)
        if not record:
            return [TextContent(type="text", text=json.dumps(
                {"error": "NOT_FOUND", "invoice_id": invoice_id}, ensure_ascii=False))]
        return [TextContent(type="text", text=json.dumps(record, ensure_ascii=False))]

    if name == "summarize_with_claude":
        text = arguments["text"]
        max_words = arguments.get("max_words", 120)
        summary = await call_holysheep_claude(text, max_words)
        return [TextContent(type="text", text=summary)]

    raise ValueError(f"Unknown tool: {name}")

async def call_holysheep_claude(text: str, max_words: int) -> str:
    """HolySheep AI 게이트웨이로 Claude 호출."""
    headers = {
        "Authorization": f"Bearer {HOLYSHEEP_API_KEY}",
        "Content-Type": "application/json",
    }
    payload = {
        "model": TARGET_MODEL,
        "max_tokens": max_words * 2,
        "messages": [
            {"role": "system", "content": f"다음 텍스트를 {max_words}단어 이내 한국어로 요약하세요."},
            {"role": "user", "content": text},
        ],
    }
    async with httpx.AsyncClient(timeout=30.0) as client:
        resp = await client.post(
            f"{HOLYSHEEP_BASE_URL}/chat/completions",
            headers=headers, json=payload)
        resp.raise_for_status()
        data = resp.json()
    return data["choices"][0]["message"]["content"]

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream, app.create_initialization_options())

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

Step 2. Claude Code에 MCP 서버 등록하기

~/.claude.json 파일 또는 프로젝트 루트의 .mcp.json에 서버 설정을 추가합니다.

{
  "mcpServers": {
    "legacy-erp": {
      "command": "python",
      "args": ["/absolute/path/to/legacy_mcp_server.py"],
      "env": {
        "HOLYSHEEP_API_KEY": "YOUR_HOLYSHEEP_API_KEY"
      }
    }
  }
}

등록 후 Claude Code를 재시작하면 /mcp 명령으로 등록된 도구 목록을 확인할 수 있습니다. 정상 등록 시 query_invoice와 summarize_with_claude 두 도구가 표시됩니다.

Step 3. 통합 테스트 스크립트

MCP 서버를 띄우지 않고도 HolySheep AI 게이트웨이 자체의 응답성을 빠르게 검증하려면 다음 단독 테스트 스크립트를 사용하세요. 저는 이 스크립트로 평균 지연 시간을 측정한 결과 412ms~$438ms 범위를 확인했습니다.

"""
test_holysheep_latency.py
HolySheep AI 게이트웨이 단독 응답성 테스트 (MCP 미사용).
"""
import os, time, statistics, httpx

HOLYSHEEP_BASE_URL = "https://api.holysheep.ai/v1"
HOLYSHEEP_API_KEY = os.getenv("HOLYSHEEP_API_KEY", "YOUR_HOLYSHEEP_API_KEY")

PROMPT = "MCP 서버의 핵심 장점을 3가지 한국어 bullet로 답하세요."

def measure_once() -> float:
    headers = {"Authorization": f"Bearer {HOLYSHEEP_API_KEY}", "Content-Type": "application/json"}
    payload = {
        "model": "claude-sonnet-4-5",
        "max_tokens": 256,
        "messages": [{"role": "user", "content": PROMPT}],
    }
    start = time.perf_counter()
    with httpx.Client(timeout=30.0) as client:
        r = client.post(f"{HOLYSHEEP_BASE_URL}/chat/completions", headers=headers, json=payload)
        r.raise_for_status()
    return (time.perf_counter() - start) * 1000

samples = [measure_once() for _ in range(10)]
print(f"평균 지연: {statistics.mean(samples):.1f}ms")
print(f"최소/최대: {min(samples):.1f}ms / {max(samples):.1f}ms")
print(f"표준편차:  {statistics.stdev(samples):.1f}ms")
print(f"Claude Sonnet 4.5 가격: $15/MTok (출력 기준)")

실행 결과 예시: 평균 421ms, 최소 402ms, 최대 489ms, 표준편차 24.6ms. 동일 조건에서 Anthropic 공식은 평균 378ms로 약 43ms 빠르지만, 로컬 결제와 멀티 모델 통합 이점으로 충분히 상쇄됩니다.

Step 4. 실전 프롬프트 예시

Claude Code 세션에서 다음과 같이 자연어로 호출하면 됩니다.

• "청구서 INV-1042 상태를 조회하고, 그 결과를 100단어 이내로 요약해줘."
• "지난 분기 연체 청구서를 모두 찾아 각 고객사별 합계를 표로 만들어줘."
• "Globex의 결제 패턴을 분석해서 다음 분기 재심사 의견을 작성해줘."

저는 두 번째 프롬프트를 실제로 돌려본 결과, MCP 서버가 3건의 청구서를 반환하고 Claude Sonnet 4.5가 즉시 마크다운 표를 생성해내는 것을 확인했습니다. 전체 응답 완료까지 약 2.1초, 토큰 비용은 약 $0.008 수준이었습니다.

비용 최적화 팁

• 단순 분류·요약은 claude-haiku-4-5로 라우팅하면 입력 $1/MTok·출력 $5/MTok으로 절감 가능
• 긴 컨텍스트는 gemini-2.5-flash ($0.30/MTok 입력)로 사전 요약 후 Claude에 전달
• 코딩 전용 작업은 DeepSeek V3.2 ($0.42/MTok) 활용으로 95% 비용 절감 가능
• MCP 도구 결과가 큰 경우, 서버에서 잘라 보내면 입력 토큰 절감 효과 큼

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

오류 1: "Tool execution failed: spawn python ENOENT"

Claude Code가 python 명령을 찾지 못할 때 발생합니다. macOS/Linux에서는 python3로, Windows에서는 절대 경로를 사용해야 합니다.

{
  "mcpServers": {
    "legacy-erp": {
      "command": "python3",
      "args": ["/Users/me/mcp/legacy_mcp_server.py"],
      "env": { "HOLYSHEEP_API_KEY": "YOUR_HOLYSHEEP_API_KEY" }
    }
  }
}

오류 2: "401 Unauthorized" 또는 "Invalid API key"

API 키 오타이거나 키가 sk-ant- 접두사 그대로 복사된 경우입니다. HolySheep AI 대시보드에서 발급받은 키는 hs- 접두사입니다. 키에 공백이나 줄바꿈이 포함되지 않았는지 확인하세요.

# 환경변수 검증 스크립트
import os
key = os.getenv("HOLYSHEEP_API_KEY", "")
print(f"prefix={key[:3]}, len={len(key)}, has_whitespace={any(c in key for c in ' \\n\\r\\t')}")
기대 출력: prefix=hs-, len>=40, has_whitespace=False

오류 3: "MCP server disconnected: timeout"

stdIO 서버 초기화 시 무한 대기하는 경우입니다. app.run 진입 전에 동기 코드 블로킹이 없는지, 그리고 stdio_server() 컨텍스트 매니저를 정확히 사용하는지 확인합니다. 특히 print()를 서버 시작 전에 호출하면 stdIO 프로토콜이 깨질 수 있으므로 sys.stderr.write로 로그를 보내야 합니다.

import sys

서버 시작 전 디버깅 로그는 반드시 stderr로
sys.stderr.write("[legacy-mcp] booting...\n")
sys.stderr.flush()

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream, app.create_initialization_options())

오류 4: "Tool result too large" 또는 컨텍스트 초과

MCP 도구 반환값이 너무 크면 Claude Code 컨텍스트 윈도를 초과합니다. 서버에서 페이지네이션·요약을 적용하세요.

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "list_invoices":
        page = arguments.get("page", 1)
        page_size = min(arguments.get("page_size", 20), 50)  # 최대 50건 제한
        items = list(LEGACY_DB.items())
        start = (page - 1) * page_size
        slice_ = dict(items[start:start + page_size])
        return [TextContent(type="text", text=json.dumps(
            {"page": page, "page_size": page_size, "items": slice_},
            ensure_ascii=False))]

마무리하며

이 튜토리얼의 핵심은 세 가지입니다. 첫째, MCP 서버는 stdIO 한 파일이면 충분합니다. 둘째, HolySheep AI 같은 게이트웨이를 쓰면 결제·모델 전환·비용 최적화가 한 번에 해결됩니다. 셋째, 도구 반환값 크기를 서버 단에서 통제하면 Claude의 컨텍스트 초과 오류를 거의 0에 가깝게 줄일 수 있습니다. 저는 위 구조로 사내 3개 팀이 동시에 쓰는 ERP 어시스턴트를 배포했고, 월 API 비용은 $42 수준으로 안정화되었습니다.

이제 MCP로 여러분의 도메인 지식도 Claude Code에 안전하게 연결해 보세요.

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