python-sdk

mcp is the official Python implementation of the Model Context Protocol (MCP), the open standard for connecting LLM applications to external tools, data, and prompts in a structured, auditable way. The package is both a server toolkit and a client library: MCPServer lets you turn plain, type-hinted Python functions into MCP tools, resources, and prompts with a decorator, deriving the JSON Schema directly from the function signature instead of requiring you to hand-write one; Client lets you connect to any MCP server over stdio, Streamable HTTP, or SSE with a few lines of async code.

Under the hood the SDK splits into a low-level protocol layer (mcp.server.lowlevel) that speaks raw JSON-RPC against the versioned MCP specification, and a high-level layer (mcp.server.mcpserver) built on top of it that handles routing, schema generation, and lifecycle so application code stays free of protocol plumbing. Transports are pluggable on both the client and server side, so a server written once can be exposed over stdio for local tool use or over HTTP for a deployed service without touching business logic. OAuth-based auth flows, structured concurrency (via anyio, supporting both asyncio and trio), and an ASGI-compatible HTTP layer (Starlette/uvicorn) are built in rather than bolted on.

The project is maintained directly by Anthropic and the MCP steering group, with a heavyweight test and CI setup (100%-enforced branch coverage, strict pyright typing, and documentation snippets that are executed as part of the test suite) reflecting its role as the reference implementation other Python MCP tooling is built against.

What You Get

• MCPServer decorator API - @mcp.tool(), @mcp.resource(...), and @mcp.prompt() turn ordinary type-hinted Python functions into MCP-callable primitives with auto-derived JSON Schema.
• Full async Client - connects to stdio, Streamable HTTP, or SSE MCP servers with a single Client(...) constructor that detects the transport automatically.
• Low-level protocol access - mcp.server.lowlevel.Server for cases that need direct control over the JSON-RPC message handling instead of the high-level wrapper.
• Built-in OAuth support - client and server auth flows (mcp.client.auth, mcp.server.auth) implemented against the MCP authorization spec.
• A CLI (mcp command, cli extra) - mcp dev, mcp run, and mcp install for local development, running servers, and installing them into hosts like Claude Desktop.
• Versioned protocol types - the mcp-types sub-package tracks multiple MCP specification revisions (e.g. 2025-11-25, 2026-07-28) so protocol upgrades are additive.

Common Use Cases

• Exposing internal tools to an LLM assistant - wrap existing Python functions (database queries, API calls, file operations) as MCP tools so any MCP-compatible host can call them safely.
• Building a deployable MCP server - run a server over Streamable HTTP with OAuth-protected access for a hosted, multi-user tool integration.
• Building an MCP client inside an application - embed Client in a Python app to call out to any MCP server, local or remote, as part of an agent loop.
• Prototyping with the MCP Inspector - use mcp dev server.py to interactively test tools/resources during development before deployment.

Under The Hood

Architecture The SDK is layered: a low-level Server (src/mcp/server/lowlevel/server.py) implements the raw JSON-RPC protocol handling, and the higher-level MCPServer (src/mcp/server/mcpserver/server.py) wraps it with decorator-based tool/resource/prompt registration, deriving JSON Schemas from Python type hints via introspection (resolve.py and the utilities/ package). Transports are decoupled behind a shared interface — stdio.py, sse.py, and streamable_http.py implement the same abstraction consumed by both client and server, so a server written once can run over any of the three standard transports unchanged. The client mirrors this structure: a high-level Client sits on top of session.py, which implements the actual MCP session state machine (capability negotiation, request/response correlation, notifications), with client/auth/ handling OAuth separately. Protocol types live in a separate workspace package, mcp-types, versioned by specification revision, so new MCP spec versions are additive rather than a rewrite of the core session logic that both client and server depend on.

Tech Stack Python 3.10+, built with hatchling and uv-dynamic-versioning (git-tag-derived versioning) inside a uv workspace spanning multiple sub-packages (mcp, mcp-types, examples). Core runtime dependencies include anyio for structured concurrency across asyncio and trio, httpx2 for HTTP, Starlette and uvicorn for the ASGI-based HTTP/SSE transports, pydantic 2.12+ for schema validation and type-hint-to-JSON-Schema derivation, sse-starlette for server-sent events, pyjwt for auth tokens, and opentelemetry-api for tracing hooks. The optional cli extra adds typer and python-dotenv to power the standalone mcp command.

Code Quality The test suite spans over a dozen subdirectories (server, client, transports, shared, docs, cli, examples, interaction, and more), and pytest-examples executes every documented code snippet under docs_src/ as part of the test run so the docs cannot silently drift from the API. Branch coverage is enforced at 100% (fail_under = 100), pyright runs in strict typing mode across source, tests, and examples, and ruff lints with a broad rule set including complexity and import-order checks plus a banned-API rule against pydantic.RootModel. CI includes a dedicated conformance workflow and a workflow-security linter (zizmor), with dependabot keeping dependencies current — a level of rigor consistent with the SDK’s role as the protocol’s reference implementation.

API Design The decorator-based MCPServer API deliberately mirrors FastAPI’s ergonomics: a type-hinted function signature like add(a: int, b: int) -> int becomes the tool’s JSON Schema with no explicit schema code, and the README frames this directly as “notice what you did not write.” The client side is equally terse — async with Client(url) as client: await client.call_tool(...) — with transport detection handled automatically from the constructor argument. Version migration between MCP spec revisions and SDK major versions is handled explicitly, with a maintained v1.x branch for teams not ready to move, a documented migration guide, and soft-deprecation warnings for legacy protocol features rather than silent breakage.