MCP Python SDK

Overview#

The MCP Python SDK is the official Python implementation of the Model Context Protocol, maintained by the modelcontextprotocol organization (a Linux Foundation project series). It provides full protocol support and a declarative development framework for exposing internal APIs, databases, and file systems through a unified protocol to any MCP-compatible AI client such as Claude or ChatGPT.

Current stable version is v1.x, with v2 in pre-alpha on the main branch. Requires Python ≥3.10 (up to 3.14), cross-platform.

Core Capabilities#

Protocol Primitives#

• Tools: Let LLMs perform actions, similar to REST POST, supporting side effects; return values auto-generate schemas from type annotations
• Resources: Expose data to LLMs, similar to REST GET, no side effects
• Prompts: Reusable LLM interaction templates

FastMCP Advanced Features#

• Structured Output: Auto-generate schemas from Pydantic BaseModel, TypedDict, dataclass annotations
• Lifespan: Type-safe startup/shutdown lifecycle management (e.g., database connection pools)
• Context Injection: Access progress reporting, logging, and session info via Context parameter
• Progress / Logging / Notifications: Long-task progress notifications, leveled logging
• Elicitation: Servers can request additional input from users
• Sampling: Servers can request the client LLM to generate text
• Completions: Auto-completion support

Transport Layer#

Client Capabilities#

• Full MCP client implementation, connect to any MCP server
• Client-side OAuth authentication
• Tool Result parsing utilities and Display Utilities

Authentication & Observability#

• JWT authentication (PyJWT) and full OAuth flows
• OpenTelemetry integration

Architecture#

FastMCP (high-level declarative framework, decorator API)
    ↓
Low-level Server/Client API (fine-grained control)
    ↓
anyio async runtime (compatible with asyncio and trio)
    ↓
Transport layer (stdio / SSE / Streamable HTTP / WebSocket)
    ↓
Starlette + Uvicorn (ASGI HTTP server)

Source layout: src/mcp/ with server/ (including FastMCP), client/, types/ (shared type definitions).

Quick Start#

uv add "mcp[cli]"

Optional dependency groups: mcp[cli] (CLI tools), mcp[ws] (WebSocket), mcp[rich] (Rich terminal output).

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Demo", json_response=True)

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers"""
    return a + b

@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    return f"Hello, {name}!"

@mcp.prompt()
def greet_user(name: str, style: str = "friendly") -> str:
    return f"Please write a warm greeting for {name}."

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Claude Code integration: claude mcp add --transport http my-server http://localhost:8000/mcp

Debugging: npx -y @modelcontextprotocol/inspector connecting to http://localhost:8000/mcp

Use Cases#

• Build MCP servers wrapping enterprise data sources for AI assistants
• Build MCP clients for autonomous AI applications
• Direct integration with AI coding assistants like Claude Code, VS Code Copilot, Cursor
• Write once, reuse across multiple LLM platforms via a unified interface layer

Quality Assurance#

• 100% test coverage target (fail_under = 100)
• Pyright strict mode type checking
• Ruff lint + format
• Pre-commit hooks

Unconfirmed Information#

• v2 (main branch, pre-alpha) release timeline not specified
• WebSocket transport's recommended status in v2 not clarified
• No official performance benchmark data found
• v2 Python SDK feature parity with TypeScript SDK requires cross-repo comparison