MCP Server 처음부터 구축하기:
AI 도구 호출 완전 개발 가이드

페인포인트: LLM 벤더마다 Function Calling 형식이 다릅니다. 모델을 바꿀 때마다 통합 계층을 처음부터 다시 작성해야 하며, LangChain Tools는 프레임워크에 묶여 IDE 간 재사용이 어렵습니다.

• 진화 경로: Function Calling(벤더 전용) → ChatGPT Plugins(플랫폼 종속) → MCP(개방 표준). Anthropic은 2024년 11월 MCP를 오픈소스로 공개하여 JSON-RPC로 AI와 외부 시스템 통신을 통일했습니다.
• 역할 분담: MCP Client는 AI 측(Claude Desktop, Cursor 등)에 위치합니다. MCP Server는 개발자가 구축하는 능력 제공자로, 하위에서 DB·API·파일 시스템에 연결하고 상위에 Tools(호출 가능 함수), Resources(읽기 전용 데이터), Prompts(재사용 템플릿)를 노출합니다.
• 전송 계층: 하위 프로토콜은 JSON-RPC 2.0이며, stdio(로컬 자식 프로세스, 저지연) 또는 HTTP + SSE / Streamable HTTP(원격·다중 클라이언트)를 지원합니다. 수명 주기는 핸드셰이크 → 능력 협상(tools/list 등) → 요청/응답 → 종료입니다.

MCP Server를 한 번 작성하면 Cursor, Claude Desktop, VS Code 등 호환 Client가 모두 호출할 수 있습니다. AI 도구 통합 분야의 USB-C 순간입니다.

언어 선택: Python(공식 mcp 패키지, FastMCP, 초보자 권장)과 TypeScript(@modelcontextprotocol/sdk, 풀스택 팀용)가 있습니다. 아래 예제는 Python을 기준으로 합니다.

python -m venv .venv
source .venv/bin/activate
pip install mcp

npm init -y
npm install @modelcontextprotocol/sdk

권장 프로젝트 구조: server.py(진입점), tools/, resources/, prompts/, tests/, pyproject.toml.

디버깅 스택: 공식 MCP Inspector(npx @modelcontextprotocol/inspector), Claude Desktop의 claude_desktop_config.json, Cursor Settings → MCP.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def say_hello(name: str) -> str:
    """지정된 이름으로 인사합니다."""
    return f"Hello, {name}! 첫 MCP 도구입니다."

if __name__ == "__main__":
    mcp.run()

python server.py 또는 npx @modelcontextprotocol/inspector python server.py로 실행합니다. Cursor·Claude Desktop 설정 후 AI 컨텍스트에서 도구가 표시되고 호출되어야 합니다.

기본 구조: 함수 시그니처가 곧 문서입니다. 파라미터·반환 타입·docstring은 JSON Schema로 변환되어 모델이 이해합니다. search_web처럼 snake_case 동사형 이름을 권장합니다.

복잡한 입력: Pydantic BaseModel과 Field(description=...)로 기본값과 필드 설명을 정의합니다.

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="검색 키워드")
    max_results: int = Field(default=5, description="최대 반환 결과 수")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """웹 검색을 실행하고 관련 결과 목록을 반환합니다."""
    ...

다섯 가지 실전 도구:

• 계산기: eval 주입을 피하고 안전한 수식 파서를 사용합니다.
• 파일 읽기/쓰기: 허용 디렉터리 화이트리스트를 적용합니다.
• HTTP 클라이언트: 외부 REST API 호출 시 타임아웃과 응답 크기 상한을 둡니다.
• 읽기 전용 SQL: 파라미터화 쿼리만 허용하고 DDL은 차단합니다.
• 시간·타임존: Agent 스케줄링에 필요한 현재 시각·변환 유틸리티입니다.

비동기 IO: 네트워크 호출은 async def와 httpx.AsyncClient를 사용하여 stdio 이벤트 루프를 블로킹하지 않습니다. 예외를 그대로 던지기보다 error·code 필드를 담은 구조화 오류를 반환하고, 프로덕션 경로에는 타임아웃과 권한 검사를 추가합니다.

Resource vs Tool: Resource는 AI가 읽는 데이터 공급자이고, Tool은 AI가 호출하는 동작 실행자입니다. Resource는 URI로 주소 지정합니다: file://, http://, custom://.

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
    return json.dumps({"version": "1.0", "env": "production"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    return json.dumps(db.query_user(user_id))

리소스 유형: 텍스트(text/plain, application/json), 바이너리(이미지·PDF), 스트리밍(실시간 시세)을 지원합니다. 파일 시스템 Server는 디렉터리 나열, 파일 읽기, 변경 이벤트 구독을 구현할 수 있습니다.

Prompts: 동적 파라미터가 주입되는 재사용 메시지 템플릿으로, 코드 리뷰·면접 시뮬레이션·디버그 어시스턴트에 적합합니다. user와 assistant 역할을 섞은 다턴 템플릿도 정의할 수 있습니다.

원격 예시: FastMCP("remote-server", transport="streamable-http")를 uvicorn으로 0.0.0.0:8000에 바인딩합니다. 프로덕션에는 Bearer Token, API Key 미들웨어, CORS 화이트리스트, 요청 빈도 제한을 적용합니다.

디버깅: MCP Inspector로 Tools 호출과 JSON-RPC 로그를 확인합니다. pytest는 mcp.client.stdio로 자식 프로세스를 기동하고 session.call_tool로 반환값을 검증합니다.

프로덕션 배포: Docker(Python 3.12-slim), Railway/Render(취미 프로젝트), Lambda/Cloud Run(서버리스), Nginx 역프록시 VPS. 구조화 로그, Prometheus 지표, Sentry 알림, /health 엔드포인트를 추가합니다. MCP 프로토콜 버전을 선언하고 도구 업그레이드는 하위 호환을 유지합니다.

실전 프로젝트: 로컬 Markdown 노트를 시맨틱 검색·생성·갱신하는 개인 지식베이스 MCP Server입니다. ChromaDB/Qdrant 벡터 저장소, text-embedding-3-small 임베딩, watchfiles로 파일 변경 시 인덱스를 자동 재구축합니다. Cursor에서 「지난주 MCP 관련 노트는?」이라고 물으면 Agent가 검색 도구를 호출해 관련 구절을 반환합니다.

2026년 참고 Server: mcp-server-filesystem, mcp-server-github, mcp-server-brave-search, mcp-server-postgres, mcp-server-slack. Cursor, Claude Desktop, VS Code, Gemini가 네이티브 MCP를 지원하며, 기업 보안 기준과 Marketplace 생태계가 성숙해지고 있습니다.

인용 가능한 기술 정보:

• 프로토콜: Anthropic이 2024년 11월 MCP(JSON-RPC 2.0)를 오픈소스했으며, 2026년 거버넌스가 Linux Foundation AAIF로 이관되었습니다.
• 생태계: 공개 MCP Server가 10,000개를 넘었습니다. Python·TypeScript SDK가 공식 유지 경로이므로 GitHub에서 버전을 재확인하십시오.
• 전송: Streamable HTTP가 순수 SSE를 대체하며 무상태 로드밸런싱에 유리합니다.

공식 문서와 SDK(배포 후 링크를 다시 열어 최신 여부를 확인하십시오):

https://modelcontextprotocol.io

https://github.com/modelcontextprotocol/python-sdk

https://github.com/modelcontextprotocol/typescript-sdk

https://github.com/modelcontextprotocol/inspector

1. 언어와 전송 모드를 선정합니다: 개인 개발은 Python + stdio, 팀 공유는 HTTP + Streamable HTTP입니다.
2. 프로젝트 골격을 구성합니다: tools / resources / prompts 모듈 분리, MCP Inspector 설치.
3. Hello World를 연동 검증합니다: Cursor 또는 Claude Desktop에서 도구 가시성·호출을 확인합니다.
4. 다섯 가지 Tools와 Resource를 확장합니다: 읽기 전용 저위험 도구부터 시작해 쓰기·외부 API를 추가합니다.
5. 단위 테스트와 Docker를 자동화합니다: CI에서 stdio 통합 테스트를 실행합니다.
6. 7×24 환경에 배포합니다: 노트북 슬립은 MCP 세션을 끊고, 순수 Linux VPS는 macOS 샌드박스·Xcode 생태계가 없습니다. 안정적인 MCP 인프라, 공유 Agent, iOS CI가 필요한 프로덕션에는 CALMVPS 베어메탈 Mac 렌탈이 대체로 최적해입니다. 전용 M4/M4 Pro, 약 120초 프로비저닝, 일/주/월/분기 탄력 과금. 기종·요금은 가격 페이지, 원격 접속은 고객 센터에서 확인하십시오.

MCP는 AI 도구화의 표준 프로토콜입니다. 오늘의 Hello World부터 시작하면 임의의 LLM에 현실 세계 능력을 확장하는 인프라 역량을 갖추게 됩니다.