MCP Python SDK

Name: MCP Python SDK MCP Server
Author: modelcontextprotocol

왜 쓰나요

핵심 기능

FastMCP 데코레이터: @tool, @resource, @prompt — 최소한의 절차
스트리밍 지원이 있는 비동기 우선 서버
테스트 및 통합을 위한 클라이언트 세션
stdio + SSE + 스트리머블 HTTP 트랜스포트
도구 입력을 위한 Pydantic 스키마

라이브 데모

실제 사용 모습

mcp-python-sdk.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-python-sdk",
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-python-sdk": {
      "command": {
        "path": "uvx",
        "args": [
          "--with",
          "mcp",
          "python",
          "-m",
          "mcp.server.example"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add mcp-python-sdk -- uvx --with mcp python -m mcp.server.example

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: MCP Python SDK

10분 이내에 Python으로 첫 번째 MCP 서버 구축

👤 MCP를 처음 접하는 Python 개발자 ⏱ ~15 min beginner

언제 쓸까: Python 함수를 Claude에 노출하고 싶을 때.

사전 조건

Python 3.10+ — uv 또는 pyenv

흐름

설치 및 스캐폴딩

Use uv to install mcp. Create server.py with one tool: get_weather(city) that calls a public API.✓ 복사됨

→ @tool 데코레이터가 있는 10줄 파일
stdio로 실행

Run mcp dev server.py. Open the MCP Inspector and verify the tool listing.✓ 복사됨

→ 인스펙터에서 도구 호출 가능
Claude Desktop에 추가

Add to claude_desktop_config.json. Test from Claude.✓ 복사됨

→ 채팅에서 라이브 응답

결과: Claude에 등록된 Python으로 작동하는 MCP 서버.

함정

핸들러에서 print() 사용 시 stdio 중단 — stderr에 로깅 사용; stdout에는 절대 쓰지 마세요

SDK 클라이언트를 사용해 MCP 서버 통합 테스트 작성

👤 프로덕션에 MCP를 퍼블리싱하는 개발자 ⏱ ~30 min intermediate

언제 쓸까: MCP가 올바르게 동작한다는 것을 증명하는 CI 테스트가 필요할 때.

흐름

서버 스폰

Use mcp.client.stdio to spawn server.py and call list_tools(). Assert expected names.✓ 복사됨

→ 테스트 통과
각 도구 호출

For each tool, call with a representative input and assert the output schema.✓ 복사됨

→ 모든 도구 검증
pytest에 연결

Convert into pytest fixtures so CI runs them on every PR.✓ 복사됨

→ 재사용 가능한 테스트 하니스

결과: 도구가 회귀하지 않는다는 확신이 있는 MCP 서버.

장시간 도구 출력을 Claude에 실시간으로 스트리밍

👤 빌드, 배포, 장시간 시뮬레이션을 위한 MCP를 구축하는 개발자 ⏱ ~45 min advanced

언제 쓸까: 도구 실행에 분이 걸리고 완료 후가 아닌 도중에 진행 상황을 채팅에서 보고 싶을 때.

흐름

스트리머블 HTTP 트랜스포트 사용

Switch from stdio to streamable HTTP. Yield progress events from the tool.✓ 복사됨

→ Claude가 실행 중에 부분 출력을 표시
취소 추가

Honor cancel requests so user can abort if the tool takes too long.✓ 복사됨

→ 실행 중간에 취소 작동

결과: 느려도 실시간처럼 느껴지는 도구.

조합

다른 MCP와 조합해 10배 효율

mcp-python-sdk + mcp-go-mark3labs

폴리글랏 — 성능 중요 부분은 Go, ML/데이터는 Python

Use mcp-python-sdk for the model-serving MCP, mcp-go for the high-throughput one.✓ 복사됨

mcp-python-sdk + mcp-registry

Python MCP를 공식 레지스트리에 퍼블리시

Submit metadata to modelcontextprotocol/registry once your server passes its tests.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출
FastMCP	name, version?	최상위 서버 생성
@server.tool	decorator on async function	노출하려는 각 함수
@server.resource	decorator with uri pattern	읽기 전용 데이터 노출
@server.prompt	decorator on prompt builder	재사용 가능한 프롬프트 템플릿
ClientSession	transport	MCP 클라이언트 테스트 또는 구축
stdio_server	()	로컬 모드

비용 및 제한

운영 비용

API 쿼터: 해당 없음 — 라이브러리
호출당 토큰: 해당 없음
금액: 무료 (MIT)
팁: pyproject.toml에서 SDK 버전 고정; 스펙이 발전함

보안

권한, 시크릿, 파급범위

자격 증명 저장: 도구에 필요한 것

데이터 외부 송신: 핸들러로 제어됨

문제 해결

자주 발생하는 오류와 해결

도구가 나타나지 않음

@tool 데코레이터가 async 함수에 있고, 서버 시작 전에 함수가 등록되었는지 확인

확인: Run `mcp dev server.py` and open the inspector

Pydantic 검증 오류

도구 입력은 Pydantic으로 검증됨; 타입 힌트가 Claude가 보내는 것과 일치하는지 확인

stdin EOF에서 서버 중단

async 핸들러가 데드락에 걸리지 않도록 확인 — 호환성을 위해 anyio 사용

대안

MCP Python SDK 다른 것과 비교

대안	언제 쓰나	단점/장점
FastMCP (PrefectHQ)	추가 유틸리티가 있는 원본 서드파티 포크를 원할 때	이제 대부분 병합됨; 얇은 래퍼
mcp-go (mark3labs)	Go가 사용 언어일 때	다른 생태계