Deployment Strategies
Relevant source files
The following files were used as context for generating this wiki page:- src/mcp/server/streamable_http_manager.py
- tests/shared/test_streamable_http.py
- examples/servers/simple-streamablehttp/README.md
- examples/servers/simple-streamablehttp-stateless/README.md
- examples/servers/simple-auth/README.md
- tests/server/fastmcp/test_server.py
- tests/server/fastmcp/test_integration.py
- CONTRIBUTING.md
- RELEASE.md
- mkdocs.yml
This document outlines the various deployment strategies and architectural patterns available for MCP (Model Context Protocol) servers developed with the Python SDK. It covers transport options, state management, authentication models, and the development-to-release lifecycle. The strategies are designed to support a range of applications, from simple monolithic servers to complex, scalable, multi-node environments.
The primary transport mechanisms discussed are SSE (Server-Sent Events) and StreamableHTTP, each offering distinct advantages. The SDK provides abstractions, such as FastMCP, to simplify the creation of ASGI-compliant applications that can be deployed with any standard ASGI server like Uvicorn.
Server Transports
The SDK supports multiple transport protocols for communication between the client and the MCP server. The choice of transport impacts the deployment architecture.
Sources: tests/server/fastmcp/test_integration.py:113-121
StreamableHTTP
The StreamableHTTP transport is a versatile option that uses standard HTTP methods (POST, GET, DELETE) for communication. It is managed by the StreamableHTTPSessionManager class.
Sources: src/mcp/server/streamable_http_manager.py:33-40, examples/servers/simple-streamablehttp/README.md
Key Features
| Feature | Description | Source Files |
|---|---|---|
| HTTP-based | Uses POST for requests, GET for long-lived notification streams, and DELETE for session termination. | src/mcp/server/streamable_http_manager.py:101-133 |
| Stateful/Stateless | Can be deployed in both stateful (session-aware) and stateless modes. | examples/servers/simple-streamablehttp-stateless/README.md |
| Resumability | Supports session resumption via an EventStore and the Last-Event-ID header. | examples/servers/simple-streamablehttp/README.md |
| JSON Responses | Can be configured to return simple JSON responses instead of streaming SSE for synchronous operations. | src/mcp/server/streamable_http_manager.py:53-54 |
HTTP Headers
The StreamableHTTP transport relies on specific HTTP headers for session management and protocol negotiation.
| Header | Purpose | Source Files |
|---|---|---|
mcp-session-id | Uniquely identifies a client session. Required for all requests after initialization. | src/mcp/server/streamable_http_manager.py:21 |
mcp-protocol-version | Specifies the MCP protocol version being used by the client. Included in requests after initialization. | src/mcp/server/streamable_http_manager.py:20 |
Accept | Must include text/event-stream for streaming responses. | tests/shared/test_streamable_http.py:504-513 |
Content-Type | Must be application/json for POST requests. | tests/shared/test_streamable_http.py:516-527 |
Sources: src/mcp/server/streamable_http_manager.py:20-21, tests/shared/test_streamable_http.py
SSE (Server-Sent Events)
The SSE transport provides a simple, unidirectional streaming connection from the server to the client over a single HTTP connection. It is suitable for scenarios where the primary need is for the server to push updates to the client.
The FastMCP class provides a convenient sse_app() method to create a Starlette application configured for SSE.
Sources: tests/server/fastmcp/test_integration.py:113-115, tests/server/fastmcp/test_server.py:50-57
Architectural Patterns
The SDK supports different architectural patterns to accommodate varying requirements for scalability, state management, and security.
Stateful vs. Stateless Deployment
The StreamableHTTP transport can be deployed in either a stateful or stateless manner, which has significant implications for scalability and infrastructure.
The diagram below illustrates the difference in request handling between stateful and stateless deployments.
This diagram shows that stateful deployments maintain session objects between requests, while stateless deployments create a new session for every request.
Sources: examples/servers/simple-streamablehttp/README.md, examples/servers/simple-streamablehttp-stateless/README.md
| Aspect | Stateful Deployment | Stateless Deployment |
|---|---|---|
| Session Management | Sessions are maintained in memory (or a persistent store) across multiple requests, identified by mcp-session-id. | A new, ephemeral session is created for each individual request. No state is preserved between requests. |
| Use Case | Applications requiring conversational context, long-running tasks, and session resumption. | APIs where each request is independent. Ideal for multi-node, load-balanced environments. |
| Implementation | StreamableHTTPSessionManager is instantiated with an EventStore (e.g., InMemoryEventStore). | StreamableHTTPSessionManager is configured with mcp_session_id=None. |
| Resumability | Supported. Clients can reconnect and replay missed events using the Last-Event-ID header. | Not applicable, as there is no persistent session to resume. |
Sources: examples/servers/simple-streamablehttp/README.md, examples/servers/simple-streamablehttp-stateless/README.md, src/mcp/server/streamable_http_manager.py:241-242
Separated Authentication (AS/RS Model)
For enhanced security and compliance with modern standards like RFC 9728, the SDK supports a deployment model where the Authorization Server (AS) and Resource Server (RS) are separate entities. In this model, the MCP server acts as the RS, protecting its resources, while a dedicated AS handles all OAuth 2.0 flows.
This diagram shows the interaction between the Client, Resource Server (MCP), and Authorization Server.
This sequence illustrates the discovery and authentication flow in a separated AS/RS architecture.
Sources: examples/servers/simple-auth/README.md
This architecture contrasts with a legacy model where the MCP server could also function as its own Authorization Server. The separated model is recommended for production environments.
Sources: examples/servers/simple-auth/README.md
Application Mounting and Serving
MCP applications built with this SDK are ASGI-compliant and can be served by any ASGI server (e.g., Uvicorn, Hypercorn). The FastMCP class simplifies the creation of a runnable Starlette application.
Using FastMCP Helpers
The FastMCP class provides sse_app() and streamable_http_app() methods that return a configured Starlette application instance.
Sources: tests/server/fastmcp/test_integration.py:112-121, tests/server/fastmcp/test_server.py:50-70
This application can be run directly with Uvicorn:
# From examples/snippets/servers/fastmcp_quickstart.py
from mcp.server.fastmcp import FastMCP
import uvicorn
mcp = FastMCP(name="Demo")
# ... tool and resource definitions ...
app = mcp.streamable_http_app()
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=8000)
Sources: tests/server/fastmcp/test_integration.py:80-97
Manual Mounting in Starlette
For more complex applications, the MCP request handler can be mounted as a sub-application within a larger Starlette or FastAPI project. This allows combining an MCP server with other HTTP endpoints.
The StreamableHTTPSessionManager's handle_request method is the ASGI application that gets mounted.
This diagram shows how an MCP application can be mounted alongside other routes in a standard ASGI framework.
Sources: tests/shared/test_streamable_http.py:284-291, tests/server/fastmcp/test_server.py:73-102
Development and Release Workflow
Deploying an MCP server also involves managing its development, testing, and release lifecycle. The project follows a structured workflow.
Development
The development process relies on uv for package management and a suite of quality tools.
| Tool | Command | Purpose |
|---|---|---|
uv | uv sync --frozen --all-extras --dev | Installs all required dependencies. |
pytest | uv run pytest | Runs the test suite. |
pyright | uv run pyright | Performs static type checking. |
ruff | uv run ruff check . --fix | Lints and automatically fixes code style issues. |
ruff | uv run ruff format . | Formats the code. |
Sources: CONTRIBUTING.md, CLAUDE.md
Release Process
The project uses a tag-based release system managed through GitHub.
This diagram outlines the steps to create a new major or minor release.
Sources: RELEASE.md
Documentation Deployment
The project's documentation is built using MkDocs with the material theme and deployed to GitHub Pages. The configuration is defined in mkdocs.yml.
Key features of the documentation deployment include:
- Automatic API Docs: The
mkdocstringsplugin generates API reference pages directly from source code docstrings. - Source Watching: The build process can watch the
src/mcpdirectory for changes and automatically rebuild the documentation. - Mermaid Diagrams: The site is configured to render Mermaid diagrams for visual explanations.
Sources: mkdocs.yml