MCP Server 처음부터 만들기
AI 도구 호출 완전 개발 가이드

AI에 MCP Server가 필요한 이유: 도구 없는 LLM은 '말만 하는 두뇌'일 뿐입니다

대규모 언어 모델의 학습 데이터에는 시한이 있어 CRM, Git 저장소, 사내 API에 접근할 수 없습니다. 2024년 이전에는 Claude용 Function Calling, GPT용 Plugins, Cursor용 별도 형식을 각각 작성해야 했고, 모델을 바꾸면 처음부터 다시 구축해야 했습니다. MCP Server는 '도구 역량'을 독립 프로세스로 캡슐화하여 한 번 작성하면 Claude Desktop / Cursor / Gemini 모두에서 사용할 수 있게 합니다.

대표 시나리오: Claude Desktop에서 AI가 Postgres 매출 데이터를 조회하고, Cursor에서 Agent가 프로젝트 문서를 읽고 코드를 수정하며, GPT가 HTTP MCP로 사내 티켓 시스템을 호출합니다. 기반은 모두 동일한 Server입니다.

본 글의 가치: 개념 설명이 아니라 say_hello에서 벡터 검색이 포함된 프로덕션급 지식 베이스 Server까지 직접 구축합니다. 대상 독자: Python 또는 TypeScript 기초가 있고 IDE·Desktop에서 AI 역량을 확장하려는 개발자입니다.

여섯 가지 핵심 과제: 'API를 직접 래핑'만으로는 부족한 이유

1. 01

   모델 벤더 종속: OpenAI Function Calling과 Claude Tool Use 형식이 달라 벤더를 바꿀 때마다 어댑터를 재작성해야 합니다.

2. 02

   도구 발견 불가: REST API는 정적 문서에 의존하며, AI가 런타임에 tools/list로 역량 목록을 자율 탐색할 수 없습니다.

3. 03

   IDE 간 비호환: Cursor, VS Code 확장, JetBrains 플러그인의 도구 정의를 공유할 수 없어 N×M 통합을 유지해야 합니다.

4. 04

   컨텍스트·데이터 단절: LLM이 설정 파일, 사용자 선호, 실시간 로그를 안정적으로 읽으려면 표준화된 Resources 읽기 전용 채널이 필요합니다.

5. 05

   Prompt 템플릿 분산: Code Review, Incident 보고 등 재사용 템플릿에 통합 등록 메커니즘이 없어 팀마다 복사·붙여넣기를 반복합니다.

6. 06

   로컬 vs 원격 배포 혼란: stdio 자식 프로세스는 개발에 적합하지만, 프로덕션 HTTP 게이트웨이·인증·모니터링에 통일된 패턴이 부족합니다(stdio 자식 프로세스 거버넌스 참고).

개발 환경 구축: Python FastMCP vs TypeScript SDK

두 가지 주류 경로가 있습니다: Python mcp + FastMCP(데이터·스크립트 친화)와 TypeScript @modelcontextprotocol/sdk(Web/API 통합·타입 안전). SDK 소스: python-sdk, typescript-sdk.

# Python 경로
python -m venv .venv && source .venv/bin/activate
pip install "mcp[cli]" httpx pydantic

# TypeScript 경로
npm init -y && npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node

권장 프로젝트 구조

my-mcp-server/
├── pyproject.toml          # 또는 package.json
├── src/
│   ├── server.py           # FastMCP 진입점
│   ├── tools/              # 각 도구 모듈
│   ├── resources/          # Resource 제공자
│   └── prompts/            # Prompt 템플릿
├── tests/
│   └── test_tools.py       # pytest + ClientSession
├── Dockerfile
└── README.md

환경 준비 6단계 체크리스트

1. 01

   언어 스택 선택: 데이터·ML 팀은 Python 우선, Node 풀스택은 TypeScript를 선택합니다.

2. 02

   가상 환경 생성 및 의존성 고정: pip freeze 또는 package-lock.json으로 schema 드리프트를 방지합니다.

3. 03

   MCP Inspector 설치: npx @modelcontextprotocol/inspector로 JSON-RPC를 시각적으로 디버깅합니다.

4. 04

   Claude Desktop 설정: ~/Library/Application Support/Claude/claude_desktop_config.json을 편집해 Server command/args를 추가합니다.

5. 05

   Cursor 설정: Settings → MCP → Add Server에서 stdio에 python -m src.server 또는 절대 경로를 입력합니다.

6. 06

   Inspector 연결 확인: Server 시작 → Inspector 연결 → tools/list가 비어 있지 않은지 확인합니다.

// Cursor / Claude Desktop MCP 설정 예시
{
  "mcpServers": {
    "my-tools": {
      "command": "python",
      "args": ["-m", "src.server"],
      "env": { "API_KEY": "your-key" }
    }
  }
}

Tools 심화 실습: Schema부터 다섯 가지 프로덕션급 도구까지

Tool은 MCP의 핵심 역량입니다. AI는 tools/call로 부수 효과가 있는 작업을 실행합니다. 각 Tool은 이름, 설명, inputSchema를 노출해야 하며, FastMCP는 Pydantic 모델로 검증을 강화합니다.

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(..., description="검색 키워드")
    limit: int = Field(10, ge=1, le=100, description="반환 건수")

@mcp.tool()
async def search_docs(params: SearchInput) -> str:
    """문서 라이브러리에서 검색"""
    results = await index.search(params.query, params.limit)
    return json.dumps(results, ensure_ascii=False)

다섯 가지 자주 쓰는 Tool 패턴

• calculator: 안전한 eval 또는 ast.literal_eval 사용, exec 금지.
• file_read / file_write: 루트 디렉터리 화이트리스트로 경로 순회 공격 방지.
• fetch_url(async): httpx 비동기 요청, timeout·도메인 화이트리스트 설정.
• db_query: 읽기 전용 SQL + 파라미터화 쿼리, DDL 금지.
• get_current_time: ISO8601 타임존 시간 반환, LLM 시간 환각 해소.

import httpx
from datetime import datetime, timezone

@mcp.tool()
async def fetch_url(url: str) -> str:
    """HTTP GET으로 URL 콘텐츠 조회(도메인 화이트리스트 내)"""
    allowed = ("api.github.com", "nodemini.com")
    if not any(url.startswith(f"https://{d}") for d in allowed):
        raise ValueError(f"Domain not allowed: {url}")
    async with httpx.AsyncClient(timeout=10.0) as client:
        resp = await client.get(url)
        resp.raise_for_status()
        return resp.text[:8000]

@mcp.tool()
def get_current_time() -> str:
    """현재 UTC 시간 반환"""
    return datetime.now(timezone.utc).isoformat()

에러 처리 모범 사례

• 구조화된 에러 반환: raise ValueError("human-readable msg")를 사용하면 Client가 message를 LLM에 전달합니다.
• 재시도 가능 vs 치명적 구분: 네트워크 타임아웃은 retryable로 표시, 권한 거부는 즉시 fail.
• 로그와 마스킹: tool 이름·소요 시간만 기록하고 API Key·PII 전체는 로그하지 않습니다.
• 멱등 설계: 쓰기 작업에 idempotency_key를 포함해 Agent 중복 호출로 인한 더티 데이터를 방지합니다.

Prompts: 재사용 가능한 다중 턴 대화 템플릿

MCP Prompt는 Server에 등록된 대화 골격입니다. Client는 prompts/get으로 메시지 목록을 가져오며, user / assistant 역할과 파라미터 자리표시자를 포함할 수 있습니다. 팀이 Code Review, Incident 절차를 공유할 때 개인 Prompt 파일을 유지할 필요가 없습니다.

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str = "python") -> list[PromptMessage]:
    """표준화된 Code Review 다중 턴 템플릿"""
    return [
        PromptMessage(role="user", content=TextContent(
            type="text",
            text=f"당신은 시니어 {language} 엔지니어입니다. 보안·성능·가독성 세 축으로 아래 diff를 검토해 주세요."
        )),
        PromptMessage(role="assistant", content=TextContent(
            type="text",
            text="diff를 붙여넣거나 PR 번호를 지정해 주세요. CHECKLIST에 따라 구조화된 review를 출력하겠습니다."
        )),
    ]

다중 턴 템플릿에 {ticket_id}, {severity} 등 변수를 중첩할 수 있으며, Server 측에서 버전을 통합 관리하면 Client가 Server를 업그레이드할 때 팀 전체가 최신 review 기준을 동기화합니다.

디버깅과 테스트: Inspector + pytest 단위 테스트

MCP Inspector는 공식 시각 디버거입니다. stdio 또는 URL에 연결한 뒤 tools/list, tools/call을 수동 전송하고 JSON-RPC 왕복을 확인할 수 있어 Cursor 로그만으로 추측하는 것보다 훨씬 효율적입니다.

# tests/test_tools.py
import pytest
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

@pytest.mark.asyncio
async def test_say_hello():
    params = StdioServerParameters(command="python", args=["-m", "src.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("say_hello", {"name": "MCP"})
            assert "MCP" in result.content[0].text

흔한 오류 대조표

실전 프로젝트: ChromaDB 지식 베이스 MCP Server

사내 Wiki / Markdown 문서를 벡터화하고 index_document, search_knowledge, write_note 세 Tool을 노출하면 Cursor Agent가 「회사 지식 베이스를 조회한 뒤 코드 작성」 워크플로를 실행할 수 있습니다.

요구사항: 증분 인덱싱(watchfiles로 docs/ 감시), 시맨틱 검색 Top-K, 선택적 scratchpad 쓰기.

import chromadb
from chromadb.utils.embedding_functions import SentenceTransformerEmbeddingFunction

client = chromadb.PersistentClient(path="./data/chroma")
collection = client.get_or_create_collection(
    "wiki", embedding_function=SentenceTransformerEmbeddingFunction()
)

@mcp.tool()
def search_knowledge(query: str, top_k: int = 5) -> str:
    """내부 지식 베이스 시맨틱 검색"""
    hits = collection.query(query_texts=[query], n_results=top_k)
    return json.dumps(hits["documents"][0], ensure_ascii=False)

@mcp.tool()
def index_document(path: str) -> str:
    """단일 Markdown 파일 인덱싱"""
    text = open(path).read()
    collection.upsert(ids=[path], documents=[text], metadatas=[{"path": path}])
    return f"Indexed: {path}"

Cursor 데모 쿼리: 「지식 베이스에서 MCP HTTP 배포 관련 문서를 검색하고 3단계 상용화 체크리스트를 요약해 줘」 — Agent가 먼저 search_knowledge를 호출한 뒤 검색 결과를 바탕으로 답변합니다. 대규모 환경에서는 Qdrant(원격 gRPC)로 벡터 DB를 교체할 수 있습니다.