MCP 2026-07-28 Migration Guide: Python SDK v2 and Stateless HTTP

Updated October 28, 2026. If your MCP server still assumes every HTTP client must initialize a session and carry an Mcp-Session-Id, the July 28 protocol revision changes the architecture you should plan for. The new Model Context Protocol (MCP) revision is designed around self-describing requests, ordinary HTTP routing, and fewer transport-level session dependencies. You can adopt it without rewriting every tool from scratch—but the Python SDK v2 migration contains real API changes.

This guide builds a small read-only MCP runbook service, connects to it with the current Python client, explains what the 2026-07-28 protocol changes, and provides a migration checklist for existing v1 projects. It separates protocol-level facts from deployment recommendations; the sample is an implementation pattern, not a claim of a live test.

Who this guide is for

• Python developers maintaining MCP clients or servers.
• Teams deploying remote MCP endpoints behind a reverse proxy or load balancer.
• Agent-platform engineers who need to understand sessionless requests, compatibility, and authorization boundaries.

What changed in MCP 2026-07-28?

The official specification published on July 28, 2026 introduces a stateless protocol core and several related changes. “Stateless” here describes the protocol exchange, not your entire application: a tool can still use a database, cache, job queue, or durable workflow state.

These are protocol changes, not performance guarantees. The maintainers describe the intended scaling and routing benefits, but actual latency, throughput, and cost depend on the application, network, model host, and deployment. Read the official July 28 release announcement and the transport specification before changing production infrastructure.

Prerequisites

• Python 3.11 or newer.
• uv for creating and locking the environment, or an equivalent Python package workflow.
• A terminal and a second terminal for the client.
• Basic understanding of Python functions, HTTP, and JSON.

The official MCP Python SDK installation guide identifies Python 3.11+ as the current requirement and documents the v2 stable line. If your application must remain on SDK v1 for now, pin it explicitly to a compatible 1.x range instead of letting a fresh dependency resolution pull in v2.

Step 1: Create a clean project

Start with a separate environment so the major SDK upgrade does not accidentally change dependencies in an existing agent service.

mkdir mcp-stateless-demo
cd mcp-stateless-demo
uv init --python 3.11
uv add "mcp[cli]"

Commit the generated project metadata and lockfile. For an existing project that is not ready for v2, use a constraint such as mcp>=1.28,<2 and follow the v1 documentation until you can migrate deliberately. Do not combine the v1-to-v2 upgrade with unrelated dependency upgrades if you need an easy rollback.

Step 2: Build a minimal, read-only MCP server

Create server.py. This example exposes a small static runbook index. It deliberately does not execute shell commands, modify files, or connect to production systems; that keeps the protocol experiment separate from dangerous side effects.

from mcp.server import MCPServer

mcp = MCPServer(
    "Ops Runbooks",
    instructions="Search the runbook index. Results are reference text, not commands to execute.",
)

RUNBOOKS = {
    "redis": "Check Redis reachability, authentication, memory pressure, and eviction metrics.",
    "nginx": "Validate configuration with nginx -t before reloading; inspect error and access logs.",
    "docker": "Inspect container health and recent logs before restarting a service.",
}


@mcp.tool()
def find_runbook(topic: str) -> str:
    """Find a read-only operational runbook by keyword."""
    query = topic.strip().casefold()
    if not query:
        return "Provide a topic such as redis, nginx, or docker."

    matches = [
        f"{name}: {text}"
        for name, text in RUNBOOKS.items()
        if query in name or query in text.casefold()
    ]
    if not matches:
        return "No matching runbook. Try redis, nginx, or docker."
    return "\n".join(matches)

The SDK derives the tool name, description, and argument schema from the function and its type hints. That is why the docstring matters: the host may present it to a model as part of the tool description. Treat tool descriptions as public interface documentation, not as a place to hide instructions or secrets.

The current SDK uses from mcp.server import MCPServer. Older v1 examples often use from mcp.server.fastmcp import FastMCP; that import path and class name changed in v2. See the official v1-to-v2 migration guide for the full list of breaking changes.

Step 3: Run the service over Streamable HTTP

Start the server:

uv run mcp run server.py --transport streamable-http

The SDK documentation uses http://localhost:8000/mcp as the local endpoint for this command. Keep this local demo bound to loopback; do not expose an unauthenticated development server to a public interface.

For a quick interface check, open a second terminal and run the official Inspector workflow:

uv run mcp dev server.py

Use the Inspector to confirm that find_runbook appears in the tool list and accepts a string argument. The Inspector is a development aid, not a substitute for authorization, integration tests, or a production deployment review.

Step 4: Connect with the v2 Python client

Create client.py:

import anyio
from mcp import Client
from mcp.types import TextContent


async def main() -> None:
    async with Client("http://localhost:8000/mcp") as client:
        print("Negotiated protocol:", client.protocol_version)

        listing = await client.list_tools()
        print("Available tools:", [tool.name for tool in listing.tools])

        result = await client.call_tool(
            "find_runbook",
            {"topic": "redis"},
        )

        if result.is_error:
            raise RuntimeError("The MCP tool returned an error")

        for block in result.content:
            if isinstance(block, TextContent):
                print(block.text)


if __name__ == "__main__":
    anyio.run(main)

Run it with uv run python client.py while the server is still running. For a current v2 server, the SDK's default mode="auto" probes server/discover and should report protocol version 2026-07-28. If it reaches an older server that does not understand discovery, the client falls back to the legacy initialization handshake. The negotiated version is the value to inspect; do not infer protocol compatibility from a successful TCP connection alone.

This expected behavior is documented in the official protocol-version guide. The code above follows the documented API shape, but it was not executed as part of preparing this article.

Step 5: Understand what “stateless” does—and does not—mean

With the newer protocol, a request contains the metadata needed for the protocol exchange, so the load balancer can send separate requests to different server instances. You no longer need to pin every modern-protocol request to the instance that created an MCP session. That can simplify horizontal scaling and remove one category of session-store coordination.

Your application can still be stateful. For example, a long-running job should store its durable state in a database or queue and return an opaque job identifier. The client can pass that identifier to a later tool call. Do not rely on process memory to preserve a workflow across replicas, restarts, or retries.

For write operations, design idempotency explicitly. A network retry can repeat a request even when the transport itself is sessionless. Use a durable operation ID, uniqueness constraint, or idempotency key where duplicate execution would be harmful. A stateless protocol does not automatically make a non-idempotent business operation safe to retry.

Step 6: Migrate an existing Python MCP project in stages

1. Inventory your dependencies. Record the current SDK version, Python version, transports, custom middleware, OAuth setup, and any code importing internal or low-level classes.
2. Upgrade in a branch. Create a lockfile for v2 and run the unit suite before changing application behavior. Keep the v1 deployment artifact available for rollback.
3. Update server imports. Replace the old FastMCP import with from mcp.server import MCPServer and instantiate MCPServer(...). Recheck constructor arguments and transport options against the migration guide.
4. Update client code. The high-level v2 client is from mcp import Client; its async context manager handles negotiation. Older code often creates a transport, wraps it in ClientSession, and calls initialize() manually. Do not mechanically mix both lifecycle patterns.
5. Rename Python attributes. SDK model attributes are snake_case in v2, such as input_schema and is_error. The JSON sent on the wire still uses the protocol's defined JSON field names; this is a Python API change, not permission to rewrite raw protocol messages arbitrarily.
6. Audit server-to-client interactions. The modern protocol does not retain the old push/back-channel behavior for server-initiated sampling, elicitation, and roots requests. Use the supported multi-round-trip flow or keep a legacy connection where the workflow genuinely requires it.
7. Test old and new hosts. Verify your intended clients negotiate the protocol you expect. SDK compatibility does not guarantee every third-party host, proxy, or adapter has implemented the new revision.
8. Review the HTTP edge. Validate host/origin rules, TLS termination, request size limits, authorization, and logs before routing public traffic to the new endpoint.

The official migration document is extensive because v2 is a major SDK rewrite, not just a transport toggle. It also documents renamed exceptions, removed helpers, changes to low-level server handlers, transport APIs, and client callbacks. Use the complete migration reference as the source of truth for your exact codebase.

Step 7: Configure remote deployment safely

For remote servers, Streamable HTTP is the recommended transport. The SDK's safe default host policy is intentionally local: an endpoint behind a public hostname may reject requests until the exact host and trusted browser origins are configured. Do not solve an HTTP 421 or 403 error by allowing every host and origin.

The official Python SDK documents an explicit allowlist pattern for an application mounted behind a trusted public hostname:

from mcp.server import MCPServer
from mcp.server.transport_security import TransportSecuritySettings

mcp = MCPServer("Ops Runbooks")

security = TransportSecuritySettings(
    allowed_hosts=["mcp.example.com", "mcp.example.com:*"],
    allowed_origins=["https://app.example.com"],
)

app = mcp.streamable_http_app(transport_security=security)

Replace the example hostnames with the real values for your deployment. Configure CORS separately for browser clients; a host allowlist and a CORS policy solve related but different problems. Behind a reverse proxy, ensure that the layer receiving traffic validates the public host and that TLS is correctly terminated and forwarded. Follow the SDK's deployment and scaling guidance before adding multiple workers.

Authorization and privacy checklist

• Use HTTPS remotely. Do not send bearer tokens over cleartext HTTP outside local development.
• Validate the token for this resource. Check issuer, audience, expiry, and scopes. Do not accept a token merely because it is a valid token for a different API.
• Never pass the inbound MCP access token through to an upstream service. If the server calls another API, obtain and validate credentials for that API separately.
• Keep tool permissions narrow. Separate read-only tools from write/destructive tools, validate arguments on the server, and require explicit human approval for high-impact actions.
• Minimize telemetry. Do not log authorization headers, refresh tokens, full private prompts, or sensitive tool results by default. Redact personal and tenant data.
• Assume tool output can be untrusted. Search results, documents, and tool descriptions may contain prompt injection. Treat retrieved text as data, not policy, and never let a model's instruction override server-side authorization.

The current MCP authorization security guidance requires servers to validate tokens intended for the specific MCP resource and explicitly forbids token passthrough. Read the official authorization security considerations before implementing OAuth.

Trade-offs and limitations

• Less protocol-session coordination: the new protocol is easier to route across replicas, but the application still needs durable state for jobs, user preferences, and transactions.
• Migration is not free: SDK v2 includes breaking Python API changes. Low-level integrations and custom transports need more attention than a small decorator-based server.
• Legacy interoperability varies: the official Python client can fall back to an older handshake, but a third-party host may have a different support matrix.
• MRTR changes interaction design: flows that assumed a server could push a question over a long-lived session need to handle a result that requests input and a follow-up call.
• Stateless is not synonymous with secure: public endpoints still require authentication, authorization, host validation, abuse controls, and safe tool design.

Troubleshooting

Related GyanAangan guides

• Build a Local Notes MCP Server in Python — for a first MCP server with SQLite tools and Inspector-based development.
• Build a Local LLM Gateway with LiteLLM — for routing, authentication, and a common API layer around local model runtimes.
• Build a Multi-Tenant LLM Quota Layer with FastAPI and Redis — for request quotas and per-tenant controls that complement an MCP gateway.
• Production RAG Engineering in 2026 — for evaluation and observability when MCP tools feed retrieval workflows.

FAQ

Does MCP 2026-07-28 mean all MCP servers are now stateless?

No. The new protocol revision removes the protocol-level session for its modern exchange. Your business logic may still use databases, queues, caches, or explicit workflow IDs. Older protocol revisions also continue to exist for compatibility.

Do I need to rewrite all tools when moving from Python SDK v1 to v2?

Not necessarily. Simple decorator-based tools may need relatively small changes, but imports, client lifecycle, type attributes, low-level handlers, and transport/auth APIs can be breaking. Follow the migration guide and test your own integration points.

Should I pin the client to 2026-07-28?

Usually start with the default automatic mode, which discovers the server's protocol and falls back when necessary. Pin a version only when you control the compatibility contract and understand the consequences of skipping discovery.

Is Streamable HTTP always better than stdio?

No. Stdio remains useful when a host launches a local server as a subprocess. Streamable HTTP is generally the right starting point for a remotely deployed server that needs normal HTTP infrastructure.

Can I deploy the sample publicly as-is?

No. The sample is intentionally read-only and minimal. A public deployment needs HTTPS, authentication, authorization, host/origin policy, request limits, monitoring, and a threat model appropriate to the data and tools it exposes.

Primary sources and further reading

• MCP maintainers: The 2026-07-28 Specification — release date and protocol changes.
• MCP 2026-07-28 transport specification — request metadata, transports, and compatibility.
• Official Python SDK installation — supported Python version and installation.
• Official Python SDK first steps — server primitives and local workflow.
• Official protocol-version guide — automatic discovery and legacy fallback.
• Official Python SDK v1-to-v2 migration guide — breaking API changes.
• Official deployment and scaling guide — host allowlists and reverse-proxy considerations.
• Official MCP authorization security considerations — token audience validation and token handling.
• Official MCP Python SDK repository — source code, issues, and release history.

Bottom line: treat MCP 2026-07-28 as a protocol and architecture migration, not just a package update. Start with a small read-only tool, inspect the negotiated version, test both new and legacy clients, and only then move stateful or privileged operations behind the new transport.