Python MCP SDK로 MCP 서버 만들기: MCPServer 도구 정의부터 Claude Code 연결까지

사내 API나 데이터베이스 조회를 AI 에이전트 도구로 노출하고 싶은데, 팀의 백엔드가 파이썬이라 TypeScript SDK 예제를 그대로 쓰기 어려운 개발자를 위한 글이다. 이 글을 따라가면 공식 Python SDK로 도구 두 개짜리 MCP 서버를 만들고, MCP Inspector로 동작을 확인하고, Claude Code에 연결하는 데까지 진행할 수 있다. 검색하면 많이 나오는 FastMCP 예제가 현재 SDK에서 어떻게 바뀌었는지도 함께 정리한다.

먼저 알아 둘 것: FastMCP에서 MCPServer로

현재 공식 SDK는 v2이며, 마이그레이션 가이드에 따르면 v1의 FastMCP 클래스가 MCPServer로 이름이 바뀌었다. 블로그나 예전 문서의 코드를 붙여 넣으면 import 단계에서 실패할 수 있으므로 차이를 먼저 확인한다.

생성자 위치 인자 변경은 오류 없이 의미만 바뀌므로 특히 주의한다. v1 코드의 FastMCP("이름", "지시문")을 클래스 이름만 바꾸면 지시문이 title로 들어간다. v2에서는 instructions=처럼 키워드로 넘긴다.

프로젝트 준비

SDK는 Python 3.11 이상이 필요하다. 공식 README는 uv로 mcp[cli]를 추가하는 방법을 안내한다. [cli]를 넣어야 mcp dev, mcp run 명령을 쓸 수 있다.

uv init ticket-mcp
cd ticket-mcp
uv add "mcp[cli]"
# pip를 쓴다면: pip install "mcp[cli]"
uv run python --version   # 3.11 이상인지 확인

도구·리소스·프롬프트 정의하기

예제로 사내 티켓 시스템을 조회하는 서버를 만든다. SDK는 함수의 타입 힌트와 docstring으로 도구의 입력 스키마와 설명을 만든다. 따라서 매개변수 타입과 docstring을 구체적으로 쓰는 것이 곧 도구 설계다.

# server.py
import sys
import logging
from typing import Literal
from mcp.server import MCPServer, Context

logging.basicConfig(stream=sys.stderr, level=logging.INFO)  # stdout 금지
log = logging.getLogger("ticket-mcp")

mcp = MCPServer("ticket-mcp", instructions="사내 티켓 조회 전용 서버. 쓰기 작업 없음.")

TICKETS = {
    "T-101": {"title": "로그인 오류", "status": "open", "owner": "kim"},
    "T-102": {"title": "결제 지연", "status": "closed", "owner": "lee"},
}

@mcp.tool()
def get_ticket(ticket_id: str) -> dict:
    """티켓 ID(예: T-101)로 제목·상태·담당자를 조회한다. 없으면 오류를 반환한다."""
    if ticket_id not in TICKETS:
        raise ValueError(f"존재하지 않는 티켓: {ticket_id}")
    return TICKETS[ticket_id]

@mcp.tool()
async def list_tickets(status: Literal["open", "closed"], ctx: Context) -> list[str]:
    """상태별 티켓 ID 목록을 반환한다."""
    await ctx.info(f"list_tickets status={status}")
    return [k for k, v in TICKETS.items() if v["status"] == status]

@mcp.resource("ticket://{ticket_id}")
def ticket_resource(ticket_id: str) -> str:
    """티켓 상세를 텍스트로 제공한다."""
    t = TICKETS.get(ticket_id)
    return f"{ticket_id} {t['title']} ({t['status']})" if t else "not found"

@mcp.prompt()
def triage(ticket_id: str) -> str:
    """티켓 분류 요청 프롬프트."""
    return f"{ticket_id} 티켓을 읽고 긴급도와 담당 팀을 제안해 줘."

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

코드에서 짚을 부분은 세 가지다. Literal["open", "closed"]로 타입을 좁히면 스키마에 허용값이 들어가 모델이 엉뚱한 값을 넣는 일이 줄어든다. ctx: Context는 v2 방식대로 인자로 받는다. 로그는 stderr로 보낸다. stdio 전송에서는 표준 출력이 프로토콜 메시지 통로이므로 print() 한 줄이 연결을 깨뜨린다. 도구 이름·입력 범위·오류 반환을 설계하는 기준은 MCP 도구 인터페이스 설계에서 따로 다뤘다.

Inspector로 먼저 확인하기

1. uv run mcp dev server.py를 실행하면 MCP Inspector가 열린다.
2. Tools 탭에서 get_ticket, list_tickets가 보이는지, 입력 스키마에 status의 허용값이 나오는지 확인한다.
3. get_ticket에 없는 ID(T-999)를 넣어 오류가 결과로 돌아오는지 본다.
4. Resources 탭에서 ticket://T-101을 읽어 본다.

Inspector에서 정상이어야 클라이언트 연결 문제와 서버 문제를 구분할 수 있다. 연결 실패나 스키마 오류를 찾는 순서는 MCP Inspector로 서버 디버깅하기를 참고한다.

Claude Code에 연결하기

Claude Code MCP 문서에 따르면 stdio 서버는 -- 뒤에 실행 명령을 적어 등록한다. uv run --directory로 프로젝트 경로를 지정하면 어느 위치에서 Claude Code를 실행해도 같은 가상 환경으로 서버가 뜬다.

claude mcp add --transport stdio ticket -- \
  uv run --directory /abs/path/ticket-mcp python server.py

claude mcp list        # 등록 확인
# Claude Code 세션 안에서 /mcp 로 연결 상태 확인

팀원과 같은 설정을 공유하려면 --scope project로 등록해 .mcp.json에 남긴다. 범위별 차이와 환경 변수 처리는 Claude Code에 MCP 서버 연결하기에 정리했다.

원격으로 배포할 때 바뀌는 것

여러 사람이 같은 서버를 쓰려면 stdio 대신 Streamable HTTP로 띄운다. README의 예시는 uv run mcp run server.py --transport streamable-http이고, 코드에서는 mcp.run(transport="streamable-http", host=..., port=...)처럼 v2 규칙대로 전송 설정을 run()에 넘긴다. 원격 서버는 인증이 필수 과제가 되므로 MCP 서버에 OAuth 붙이기의 항목을 함께 확인한다. TypeScript로 같은 구조를 만드는 방법은 TypeScript SDK로 최소 MCP 서버 만들기에 있다.