modelcontextprotocol/python-sdk

This system is the official Python SDK for the Model Context Protocol (MCP), providing the core client and server implementations for building AI agent integrations. It enables developers to create MCP-compliant servers that expose tools, resources, and prompts, while offering robust clients that connect via stdio, SSE, or Streamable HTTP transports. The SDK includes comprehensive support for modern authentication flows, including OAuth 2.0 with PKCE and enterprise identity assertions, alongside utilities for protocol versioning, type safety, and local server management.

19 changes.

This period focused on restructuring the MCP Python SDK for version 2, introducing a new MCPServer API, separating protocol types into a standalone package, and aligning with the 2024-10-07 and 2026 protocol specifications. The work involved removing legacy client and server implementations, adding comprehensive test coverage for the new architecture, and providing extensive documentation and example servers to demonstrate modern features like Streamable HTTP and OAuth.

22 changes.

This period focused on implementing comprehensive OAuth 2.0 support for both MCP servers and clients, including a new authorization server, middleware, and client-side flows like PKCE and identity assertion. The work was accompanied by extensive regression and contract testing to ensure protocol compliance and security, alongside new examples demonstrating these authentication patterns.

23 changes.

This period focused on implementing the new MCPServer class with structured error handling, security features, and support for prompts, resources, and OAuth. The work included splitting protocol types into a standalone package and introducing a comprehensive suite of end-to-end and unit tests to validate the server's capabilities, transports, and documentation examples.

Added a new example server, the MCP Everything Server, which implements all Model Context Protocol (MCP) features to serve as a reference implementation for conformance testing. This server allows users to validate their MCP client and server implementations against the full protocol specification by running it locally (defaulting to port 3001) and using the MCP Conformance Test Framework.

examples/servers/everything-server · high confidence

A new example server demonstrating the SSE polling pattern with server-initiated stream close for long-running tasks has been added. It includes a \process\_batch\ tool that simulates work with periodic checkpoints, triggering stream closures to allow client auto-reconnection via Last-Event-ID. The demo supports configurable retry intervals and is accessible via the \mcp-sse-polling-demo\ command.

_examples/servers/simple-resource, examples/servers/simple-resource/mcp\_simple\resource, examples/servers/sse-polling-demo · high confidence

New example scripts have been added to the \examples/snippets/servers/lowlevel\ directory to demonstrate how to build MCP servers using the low-level API. These snippets cover basic prompt and tool handling, direct \CallToolResult\ returns with \\_meta\ fields for OpenAI Apps compatibility, lifespan management for resource initialization (such as database connections), and structured output schemas for tool responses.

examples/servers/structured-output-lowlevel, examples/snippets/servers/lowlevel · high confidence

A new example server, mcp\_simple\_tool, is introduced to demonstrate how to implement and expose a tool that fetches website content. The server registers a 'fetch' tool that accepts a URL, performs an HTTP GET request with a specific User-Agent and timeout, and returns the response text. It supports both stdio and streamable-http transports, binding to localhost by default for HTTP mode.

_examples/servers/simple-tool/mcp\_simple\tool · high confidence

Added a new example client in the examples/clients/simple-chatbot directory that demonstrates integrating the Model Context Protocol (MCP) into a simple CLI chatbot. The implementation showcases MCP's flexibility by supporting multiple tools through MCP servers and is compatible with any LLM provider that follows OpenAI API standards. It includes a README with installation and usage instructions, a .python-version file specifying Python 3.10, and requires dependencies like python-dotenv, requests, mcp, and uvicorn.

_examples/clients/simple-chatbot, examples/clients/simple-chatbot/mcp\_simple\chatbot · high confidence

A new example server (\mcp\_simple\_prompt\) is introduced to demonstrate prompt handling capabilities. It exposes a single 'Simple Assistant Prompt' that accepts optional \context\ and \topic\ arguments, allowing users to provide additional background or focus areas for the generated response. The server supports both stdio and streamable-http transports, binding to localhost by default for HTTP.

_examples/servers/simple-prompt/mcp\_simple\prompt · high confidence

The documentation source has been reorganized into topical sections (apps, asgi, authorization, caching, client, client\_callbacks, client\_transports, completions, context, dependencies, deploy, elicitation, extensions, first\_steps, handling\_errors, identity\_assertion, and legacy\_clients). Each section contains runnable Python tutorial files that are included in the documentation via \--8\<--\ and executed by CI tests, ensuring the examples remain accurate and up-to-date.

_docs\src · high confidence

A new \mcp\ CLI tool is added to manage and run MCP servers, providing commands to launch servers locally and automatically configure Claude Desktop. The CLI validates that server objects are instances of \MCPServer\, generates absolute paths for server scripts, and updates Claude's configuration JSON to use \uv run\ with a pinned SDK version and the \--frozen\ flag for reproducible environments.

src/mcp/cli · high confidence

The repository now includes a comprehensive suite of executable example programs (stories) under \examples/stories/\. Each story is a standalone, self-verifying program consisting of a \server.py\ and a \client.py\ that runs assertions and exits non-zero on failure. The suite provides a standardized harness (\\_harness.py\, \\_hosting.py\) for running these examples over both stdio and HTTP transports, including self-hosting capabilities for HTTP. The stories cover a wide range of features including tools, prompts, resources, lifespan, dual-era protocol support, streaming, authentication (bearer, OAuth), and various extensions like MCP Apps. This suite serves as both documentation and a test matrix, ensuring that public APIs and examples remain consistent with the SDK's implementation.

examples/stories · high confidence

This change adds a new \src/mcp/server/auth/middleware\ package containing four key components: \BearerAuthBackend\ for validating Bearer tokens and enforcing resource-server URL matching, \RequireAuthMiddleware\ for checking required scopes and returning proper 401/403 responses with WWW-Authenticate headers, \AuthContextMiddleware\ for storing the authenticated user in a context variable for easy access during the request lifecycle, and \ClientAuthenticator\ for validating client credentials (including client\_secret\_basic and client\_secret\_post) at the OAuth token endpoint. These components collectively enable the MCP server to perform standard OAuth 2.0 authentication and authorization flows.

src/mcp/server/auth/middleware · high confidence

The \src/mcp/server/auth\ module now provides a complete OAuth 2.0 Authorization Server implementation for the MCP protocol. This includes route definitions for standard endpoints (authorization, token, registration, revocation) and metadata discovery, along with middleware for CORS and request body limits. The server supports client authentication via \client\_secret\_basic\ and \client\_secret\_post\, validates issuer URLs to enforce HTTPS (with exceptions for loopback addresses), and advertises support for the ID-JAG grant profile (RFC 8693 token exchange) when identity assertion is enabled. A custom JSON response handler ensures proper serialization of Pydantic models.

src/mcp/server/auth · high confidence

The \src/mcp/client\ package has been introduced, providing a complete client implementation for the MCP protocol. This includes a new \Client\ class and \ClientSession\ for managing connections, along with transports for SSE (\sse\_client\) and stdio (\stdio\_client\). Key features include automatic protocol version negotiation (\mode='auto'\) via the \\_probe\ module, support for multi-round \InputRequiredResult\ handling (SEP-2322), and a new \subscriptions/listen\ driver for real-time change events. The package also introduces a \ClientExtension\ API for customizing client behavior, a response caching mechanism, and an \InMemoryTransport\ for testing servers without network overhead. The CLI entry point has been updated to use \argparse\ instead of \click\ and now supports custom client info.

src/mcp/client · high confidence

Added a new example client in \examples/clients/sse-polling-client\ that demonstrates the SSE polling pattern (SEP-1699) with automatic reconnection. This demo client connects to an SSE polling server, handles stream closures by resuming from the Last-Event-ID to avoid missing messages, and respects server-provided retry intervals. It serves as a reference implementation for clients needing robust long-running task handling via SSE polling.

examples/clients/sse-polling-client · high confidence

Added a new set of example scripts in the \examples/snippets/clients\ directory demonstrating various client capabilities. These include basic stdio and streamable HTTP connections, OAuth and enterprise identity assertion authentication flows, pagination handling, prompt and resource template argument completion, tool result parsing (text, structured, embedded resources, images), and URL elicitation workflows with security warnings.

examples/snippets/clients · high confidence

Added five new scripts to the \scripts/\ directory to support the v2 documentation site and protocol type generation: \build-docs.sh\ and \serve-docs.sh\ build and serve the combined v1/v2 documentation site using Zensical (with MkDocs fallback for v1); \gen\_surface\_types.py\ regenerates per-version wire-shape Python types from vendored JSON schemas, applying specific patches for schema defects and handling server info metadata; \test\ runs the test suite with coverage and strict-no-cover checks; and \update\_readme\_snippets.py\ keeps README code examples in sync with source files.

scripts · high confidence

Added a comprehensive suite of documentation tutorials and example servers under \docs\_src/\ and \examples/\ to demonstrate the new \MCPServer\ API. These include guides for client-side caching, dependency injection with \Resolve\, elicitation workflows, lifespan management, structured output, and low-level server construction. The examples also showcase advanced features such as complex input validation, direct \CallToolResult\ returns, and a full conformance test server implementing all MCP capabilities including image/audio content, subscriptions, and stateless HTTP.

mcp · high confidence

The \examples/servers/simple-auth/mcp\_simple\_auth\ package now provides a complete, runnable example of an MCP server implementing the OAuth 2.0 Authorization Server (AS) and Resource Server (RS) separation. It includes a \SimpleOAuthProvider\ for handling the OAuth flow with a demo login UI, and a \ResourceServer\ that validates tokens via introspection (RFC 7662) and serves MCP tools. The example supports both SSE and streamable-HTTP transports, implements RFC 9728 Protected Resource Metadata, and optionally enforces RFC 8707 resource validation via the \--oauth-strict\ flag. It also includes a \py.typed\ marker for type checking support.

_examples/servers/simple-auth/mcp\_simple\auth · high confidence

Added a new example client (\mcp\_simple\_auth\_client\) that demonstrates connecting to an MCP server using streamable HTTP transport with OAuth authentication. The client includes an in-memory token storage implementation, a local callback server to handle OAuth redirects, and support for validating the \iss\ parameter in authorization responses.

_examples/clients/simple-auth-client/mcp\_simple\_auth\client · high confidence

Added a new example server (\mcp-simple-pagination\) that demonstrates how to implement cursor-based pagination for tools, resources, and prompts using the low-level server API. The server exposes 25 paginated tools (5 per page), 30 paginated resources (10 per page), and 20 paginated prompts (7 per page), returning a \nextCursor\ when more pages are available. It supports both stdio and Streamable HTTP transports, allowing users to retrieve subsequent pages by passing the cursor in their requests.

examples/servers/simple-pagination · high confidence

A new example server located at examples/servers/simple-streamablehttp-stateless demonstrates a stateless Streamable HTTP MCP server. It exposes a single tool, start-notification-stream, which sends a configurable number of log notifications with a specified interval. The server binds to 127.0.0.1 by default, supports JSON responses via a CLI flag, and includes CORS middleware to allow browser-based clients to access the Mcp-Session-Id header.

_examples/servers/simple-streamablehttp-stateless/mcp\_simple\_streamablehttp\_stateless, examples/servers/simple-streamablehttp/mcp\_simple\streamablehttp · high confidence

The server now includes a new \utilities\ package providing helper tools for developers. This includes context injection utilities that automatically detect and inject \Context\ objects into function parameters, standardized logging configuration with optional Rich console support, and new \Image\ and \Audio\ helper classes that simplify creating media content by handling file paths, binary data, and MIME type detection for MCP protocol responses.

src/mcp/server/mcpserver/utilities · high confidence

The protocol message models, JSON-RPC envelope types, per-version surface validators, and protocol-version registry are now available as a standalone \mcp\_types\ package. This allows users to install and use \pydantic\-based validation for (de)serializing MCP traffic without pulling in the full \mcp\ SDK. The package exposes a monolithic API (e.g., \from mcp\_types import Tool, CallToolRequest\) that re-exports the latest schema types, while internally routing validation through version-specific modules (\\_v2025\_11\_25\, \\_v2026\_07\_28\) to support multiple protocol revisions. The \mcp\ package continues to re-export these names for backward compatibility.

src/mcp-types · high confidence

The client now supports the SEP-990 Identity Assertion Authorization Grant (ID-JAG) flow, allowing enterprise users to authenticate using a signed JWT issued by their identity provider. This new \IdentityAssertionOAuthProvider\ handles the RFC 7523 jwt-bearer grant type, fetching metadata from a configured authorization server issuer and exchanging the identity assertion for an MCP access token. The implementation also introduces stricter security controls by ensuring HTTP redirects are only followed within the same origin as the configured issuer, preventing potential redirection to unauthorized endpoints.

src/mcp/client/auth/extensions · high confidence

The \mcp\_python/client\ module has removed the previous \ClientSession\ class and the dedicated transport implementations for SSE (\sse.py\) and stdio (\stdio.py\). This change eliminates the legacy code paths for establishing client connections and handling session logic, indicating a shift in how the library manages client-side communication and protocol interactions.

_mcp\python/client · high confidence

The \mcp\_python/server\ package has been completely removed, deleting the legacy \Server\ class, \ServerSession\, and transport implementations (stdio, SSE, and WebSocket). This eliminates the previous server-side API and transport layer from the product.

_mcp\python/server · high confidence

The SDK now exposes the \mcp\_types\ package's protocol definitions (including JSON-RPC types, method registries, and version constants) under the \mcp.types\ namespace. This allows users to import types using the familiar \mcp.types\ spelling (e.g., \from mcp.types import TextContent\) without directly depending on the separate \mcp\_types\ distribution, while maintaining compatibility with existing code that imports from \mcp\_types\ directly.

src/mcp/types · high confidence

The example servers in the examples/mcpserver directory have been updated to use the renamed MCPServer class instead of the previous FastMCP name. Additionally, the text\_me example now uses the httpx2 library for HTTP requests, replacing the previous httpx dependency.

examples/mcpserver · high confidence

The examples/snippets/servers directory now provides a collection of runnable server demonstrations using the renamed MCPServer class. These examples cover basic tools, resources, prompts, completions, and image handling, and demonstrate modern transport configurations such as stateless HTTP with JSON responses and Starlette mounting (including path and host-based routing). The set also includes examples for OAuth/protected resource authentication via AuthSettings and token verification, as well as progress reporting and sampling.

examples/snippets/servers · high confidence

The \src/mcp/shared\ package now provides the core infrastructure for the MCP 2026 protocol revision, including a new \Dispatcher\ protocol that decouples transport logic from MCP semantics, context-aware memory streams that preserve \contextvars\ across task boundaries, and strict HTTP redirect handling that limits redirections to the endpoint's origin. It also introduces security primitives for validating filesystem paths against traversal attacks, utilities for OAuth 2.0 Resource Indicators (RFC 8707), and OpenTelemetry tracing helpers. Additionally, the package adds support for URL-mode elicitation via a new \UrlElicitationRequiredError\ and deprecation warnings for legacy capabilities like sampling and roots.

src/mcp/shared · high confidence

The server module has been restructured for the v2 release, renaming the primary server class from FastMCP to MCPServer (with a dedicated error module for migration) and introducing full support for the 2026-07-28 protocol era, including stateless Streamable HTTP, per-request log-level opt-ins, and pluggable subscriptions. Security is strengthened by binding transport sessions to authenticated principals, enforcing request body limits across SSE and OAuth endpoints, and adding integrity protection for multi-round-trip request states. The SDK also adds OpenTelemetry middleware with GenAI semantic conventions, supports Python 3.14, and deprecates legacy roots, sampling, and logging methods in alignment with the new specification.

src/mcp/server · high confidence

The MCP package has been reorganized under the \src/mcp\ namespace, introducing a standalone \mcp-types\ package for protocol definitions and adding a \py.typed\ marker for proper type checking support. This change significantly expands the public API by exposing new capability types (such as \PromptsCapability\, \ResourcesCapability\, \SamplingCapability\, and \ToolsCapability\), tool-related content types (\ToolChoice\, \ToolResultContent\, \ToolUseContent\), and new error classes (\MCPDeprecationWarning\, \UrlElicitationRequiredError\). Additionally, the package now exports a new \Client\ class and \ClientSessionGroup\ for managing multiple session connections, while renaming \McpError\ to \MCPError\ and flattening parameter structures for better ergonomics.

src/mcp · high confidence

The MCPServer now provides a more robust and secure interface for building MCP servers. It introduces specific exception classes (ResourceError, ToolError, etc.) to distinguish between anticipated failures and unexpected crashes, ensuring that detailed error messages and tracebacks are not exposed to clients during crashes. Additionally, it enforces integrity protection for request state using AES-GCM encryption and returns a specific protocol error code (-32602) when a resource is not found, aligning with SEP-2164.

src/mcp/server/mcpserver · high confidence

The client authentication module has been replaced with a new implementation supporting the OAuth 2.0 Authorization Code flow with PKCE and automatic token refresh. This change introduces specific exception types for flow, token, and registration errors, and implements logic to handle scope selection and unioning during step-up re-authorization (SEP-2350). It also adds support for appending the 'offline\_access' scope for refresh tokens when supported by the authorization server (SEP-2207) and follows updated discovery URL ordering for protected resource and authorization server metadata.

src/mcp/client/auth · high confidence

The server now introduces a dedicated \ResourceManager\ and a suite of concrete resource types (\FileResource\, \HttpResource\, \FunctionResource\, etc.) to handle resource serving. This change adds support for URI templates with operator-aware security validation, allowing dynamic resource generation while enforcing security policies. \FileResource\ now uses an explicit \encoding\ field (defaulting to \utf-8-sig\ for text) instead of a binary flag, and \FunctionResource\ supports lazy loading with proper async/sync handling. The system also passes \InputRequiredResult\ through the resource pipeline to support multi-round-trip flows.

src/mcp/server/mcpserver/resources · high confidence

Added platform-specific utilities in src/mcp/os to handle child process lifecycle and stdio isolation. On POSIX, the new terminate\_posix\_process\_tree function ensures that process groups are terminated atomically using SIGTERM and SIGKILL, preventing orphaned processes. On Windows, the module introduces Job Object support to group child processes for clean termination, a FallbackProcess wrapper to support async operations on event loops lacking native subprocess support, and logic to rebind standard handles so that subprocesses correctly inherit stdin/stdout/stderr streams.

src/mcp/os · high confidence

The prompt rendering pipeline in the server has been updated to handle cases where a prompt requires additional input from the user. The \PromptManager.render\_prompt\ method now returns either a list of messages or an \InputRequiredResult\, allowing the server to properly signal when a prompt cannot be fully rendered without further user interaction.

src/mcp/server/mcpserver/prompts · high confidence

The \mcp\_python\ package has updated its type definitions to align with the Model Context Protocol specification version 2024-10-07. This change ensures that the Python bindings correctly reflect the latest protocol requirements, including adjustments to request and notification method generics and structured capability types.

_mcp\python · high confidence

The simple-prompt example server now explicitly pins the Python runtime to version 3.10 via a new .python-version file and documents support for the Streamable HTTP transport in its README, allowing users to start the server with the --transport streamable-http flag.

examples/servers/simple-prompt · high confidence

Added comprehensive test suite for MCPServer; Added comprehensive test suite for server authentication and OAuth flows; Added end-to-end OAuth interaction tests for the SDK's authorization server and client; Added integration tests for MCP server OAuth authorization; Added interaction tests for MCPServer capabilities; Added low-level interaction tests for the 2026-07-28 protocol; Added regression tests for MCP server issues; Added shared test suite for MCP protocol components; Added stdio lifecycle and cross-platform transport tests; Added story-style examples suite with comprehensive test coverage; Added tests for CLI configuration and utility functions; Added tests for MCP server tool error handling and context detection; Added tests for auth middleware components; Added tests for client credentials and identity assertion OAuth providers; Added tests for documentation source examples; Added tests for low-level server helper types, discovery, and listing handlers; Added tests for prompt rendering and management; Added tests for server resource handling and security; Added tests for the mcp-types package split and protocol versioning; Client test suite: new fixtures, OAuth, caching, extensions, and transport tests; Initial test suite for MCP protocol types and example servers; New end-to-end interaction test suite with requirements manifest; New in-process transport test suite for Streamable HTTP and stdio; New test suite for server-side functionality.

The MCP Python SDK has been upgraded to version 2, introducing a standalone \mcp-types\ package for wire protocol types and replacing the \httpx\ and \httpx-sse\ dependencies with \httpx2\. The main \mcp\ package now depends on \mcp-types\ and requires \pydantic\>=2.12.0\, \anyio\>=4.9\ (or \\>=4.10\ for Python 3.14), and \sse-starlette\>=3.0.0\. This release also adds a comprehensive suite of example projects under \examples/\, including clients (\simple-auth-client\, \simple-chatbot\, \sse-polling-client\) and servers (\everything-server\, \simple-auth\, \simple-pagination\, \simple-prompt\, \simple-resource\, \simple-streamablehttp\, \simple-tool\, \sse-polling-demo\, \structured-output-lowlevel\), each with their own \pyproject.toml\ or \requirements.txt\ defining dependencies like \click\, \uvicorn\, and \starlette\.

(dependencies) · high confidence

The repository is initialized with foundational configuration files including a pre-commit hook setup (enforcing ruff formatting/linting, pyright type checking, and markdownlint), a uv.lock dependency manifest, and comprehensive documentation files (AGENTS.md, CONTRIBUTING.md, DEPENDENCY\_POLICY.md, VERSIONING.md, SECURITY.md, RELEASE.md, ROADMAP.md) that define the project's branching model, code quality standards, testing requirements (100% coverage), and release processes for the v2 stable line and v1.x maintenance line.

(repo-wide) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 71.

• Code Health 88
• Architecture 98
• Maturity 69
• Readiness 62
• Security 86

• 300 commits — 258 feature/other, 42 fixes

• src/mcp — 121 commits
• (root) — 60 commits
• .github/workflows — 18 commits
• .github/actions — 16 commits
• examples/stories — 12 commits
• tests/interaction — 11 commits
• docs/migration.md — 10 commits
• tests/server — 7 commits
• tests/client — 6 commits
• .github/scripts — 3 commits
• docs/advanced — 3 commits
• examples/servers — 3 commits
• i18n/de — 3 commits
• tests/docs_src — 3 commits
• docs/client — 2 commits
• scripts/docs — 2 commits
• scripts/gen_surface_types.py — 2 commits
• src/mcp-types — 2 commits
• tests/shared — 2 commits
• tests/transports — 2 commits

• fix: Ask which release line a bug report is on (#3213)
• fix: Fix 404 links in v1 README to renamed example files (#2822)
• fix: Fix docs/release follow-ups from the mcp-types package split (#2977)
• fix: Fix leaked anyio streams in streamable_http (#1991)
• fix: Fix stdio client shutdown bugs and rebuild the stdio test suite (#2773)
• fix: Fix unknown-method error code and add a protocol version registry (#2836)
• fix: OAuth client: harden SEP-2352/SEP-2350 edge cases; fix conformance comment (#2936)
• fix: fix(auth): coerce empty-string optional URL fields to None in OAuthClientMetadata (#2404)
• fix: fix(oauth): include client_id in token request body for client_secret_post (#2185)
• fix: fix: accept wildcard media types in Accept header per RFC 7231 (#2152)
• fix: fix: add 'invalid_target' to AuthorizationErrorCode (RFC 8707) (#2642)
• fix: fix: add HTTP readiness check to wait_for_server and remove dead code in SSE tests (#2073)
• fix: fix: align Context logging methods with MCP spec data type (#2366)
• fix: fix: allow null id in JSONRPCError per JSON-RPC 2.0 spec (#2056)
• fix: fix: cancel in-flight handlers when transport closes in server.run() (#2306)
• fix: fix: catch PydanticUserError when generating output schema (pydantic 2.13 compat) (#2434)
• fix: fix: chain exceptions in get_prompt and read_resource handlers (#2542)
• fix: fix: clean up SSE session on client disconnect (#2200)
• fix: fix: close all memory stream ends in client transport cleanup (#2266)
• fix: fix: correct Context type parameters across examples and tests (#2256)
• …and 280 more

• 0 containers · 1 bounded contexts · 0 dependency edges (baseline)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

modelcontextprotocol/python-sdk was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.