Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The python-sdk provides a robust framework for building client and server applications that communicate using the Model Context Protocol (MCP). The architecture is designed to be modular, supporting multiple communication transports and a clear separation between the protocol logic and the application-specific implementation. Key components include a high-level FastMCP server framework, transport-specific handlers for SSE and StreamableHTTP, and a ClientSession class for managing client-side interactions.
The system facilitates rich interactions beyond simple request-response, enabling features like server-pushed notifications, long-running tool progress updates, and client-side callbacks for user input (elicitation) or model responses (sampling). Authentication is a first-class citizen, with a design that promotes modern, secure standards like OAuth 2.0 and RFC 9728.
Core Components
The architecture is centered around a few key classes that manage the client-server lifecycle and communication.
This diagram shows the high-level relationship between the client application, the transport layer, and the server components.
Sources: src/mcp/client/session.py, src/mcp/server/fastmcp/test_server.py, src/mcp/server/streamable_http.py
FastMCP Server
The FastMCP class is the primary entry point for creating an MCP server. It simplifies development by providing decorators to register tools, resources, and prompts. It internally manages ToolManager, ResourceManager, and PromptManager to handle the respective functionalities.
@mcp.tool(): Registers a Python function as an executable tool. The manager handles input validation based on type hints and serializes the output.@mcp.resource(): Registers a function to provide a resource, which can be static or dynamic based on URI templates (e.g.,resource://{org}/{repo}/data).@mcp.prompt(): Registers a function that generates a prompt, which can be retrieved by the client.
The FastMCP class can expose the server over different transports by calling methods like sse_app() or streamable_http_app(), which return Starlette-compatible ASGI applications.
Sources: tests/server/fastmcp/test_server.py:18, tests/server/fastmcp/test_server.py:165, tests/server/fastmcp/test_server.py:182, tests/server/fastmcp/test_server.py:901
ClientSession
The ClientSession class is the main interface for client applications to interact with an MCP server. It abstracts the underlying transport and message passing, providing high-level async methods for common operations:
initialize(): Establishes and initializes the session.list_tools(),call_tool(): Discovers and executes server-side tools.list_resources(),read_resource(): Discovers and reads server-side resources.list_prompts(),get_prompt(): Discovers and retrieves server-side prompts.
The session can be configured with callbacks (sampling_callback, elicitation_callback) to handle requests initiated by the server.
Sources: src/mcp/client/session.py, tests/server/fastmcp/test_integration.py:284, tests/server/fastmcp/test_integration.py:382
Communication Transports
The SDK supports two primary communication transports, both built on top of HTTP.
| Feature | SSE (Server-Sent Events) | StreamableHTTP |
|---|---|---|
| Endpoint | /sse (by default) | /mcp (by default) |
| Communication | A single, long-lived HTTP connection for bidirectional communication. | A combination of POST for client-to-server messages, GET for a server-to-client event stream, and DELETE for session termination. |
| Session ID | Implicitly managed by the connection. | Explicitly managed via the mcp-session-id HTTP header. |
| Resumability | Not natively supported. | Supported via Last-Event-ID header and an EventStore on the server. |
| Response Format | Always text/event-stream. | Can be text/event-stream or application/json based on server config (json_response). |
Sources: tests/server/fastmcp/test_integration.py:133, src/mcp/server/streamable_http.py, examples/servers/simple-streamablehttp/README.md
StreamableHTTP Flow
StreamableHTTP is a more complex but flexible transport. It uses standard HTTP methods for different aspects of the session, making it compatible with environments where long-lived connections are challenging.
A typical session lifecycle is as follows:
- Initialization: The client sends a
POSTrequest to the/mcpendpoint to initialize a new session. The server responds with a uniquemcp-session-idin the response headers. - Event Stream: The client immediately sends a
GETrequest to the same/mcpendpoint, including themcp-session-idheader. This connection is held open by the server to push notifications. - Operations: The client sends subsequent
POSTrequests for operations liketools/call, including themcp-session-idto identify the session. - Termination: The client sends a
DELETErequest to terminate the session.
Sources: src/mcp/server/streamable_http.py, tests/shared/test_streamable_http.py
The following diagram illustrates the session initialization and an operation call.
StreamableHTTP Headers
This transport relies on custom HTTP headers to manage sessions and protocol versions.
| Header | Purpose | Used In |
|---|---|---|
mcp-session-id | Uniquely identifies a client session. Must be included in all requests after initialization. | POST, GET, DELETE |
mcp-protocol-version | Specifies the protocol version being used. Sent by the client after being negotiated during initialization. | POST, GET, DELETE |
Last-Event-ID | Used by the client to tell the server the ID of the last event it received, enabling session resumption. | GET |
Sources: src/mcp/server/streamable_http.py:16-17, tests/shared/test_streamable_http.py:1086-1102
Authentication Architecture
The SDK includes a sophisticated authentication system based on OAuth 2.0, designed to align with modern security best practices like RFC 9728. This specification separates the Authorization Server (AS) from the Resource Server (RS).
- Resource Server (RS): The MCP server itself, which protects its resources (tools, etc.) and validates access tokens.
- Authorization Server (AS): A separate server responsible for authenticating users and issuing access tokens.
This separation of concerns enhances security and modularity.
Sources: examples/servers/simple-auth/README.md
Authentication Flow (RFC 9728)
The client discovers the authorization server via the resource server.
This diagram shows the discovery and authentication flow where the MCP server is a Resource Server.
Sources: examples/servers/simple-auth/README.md, tests/server/auth/middleware/test_bearer_auth.py
The BearerAuthBackend middleware on the server is responsible for extracting the bearer token from the Authorization header, verifying it, and populating the request scope with an AuthenticatedUser and AuthCredentials. The RequireAuthMiddleware can then be used to protect specific routes, ensuring the authenticated user has the required scopes.
Sources: tests/server/auth/middleware/test_bearer_auth.py:13, tests/server/auth/middleware/test_bearer_auth.py:202
Summary
The python-sdk architecture is a well-defined system for building applications on the Model Context Protocol. It provides a developer-friendly FastMCP server framework that abstracts away protocol complexities, allowing developers to focus on business logic by writing simple Python functions. The support for multiple transports (SSE and StreamableHTTP) offers flexibility for different deployment environments. The StreamableHTTP transport, with its session management and resumability features, is particularly robust. Finally, the decoupled authentication model based on OAuth 2.0 and RFC 9728 ensures that security is handled in a standardized and scalable manner.