Stateless MCP Scale Demo

A small, production-minded demonstration of the MCP 2026-07-28 stateless protocol core.

The same multi-step purchase workflow is served by two independent MCP replicas behind an ordinary Nginx round-robin load balancer. There are:

• no protocol sessions;

• no sticky routing;

• no shared session database;

• no hidden in-memory workflow state.

Instead, every mutating tool returns an explicit, HMAC-signed request_handle. The client passes that handle into the next tool call, and any replica with the shared signing key can validate it and continue the workflow.

This demo is intentionally small. It illustrates architecture, not a complete authorization or purchasing system.

Why this exists

The 2026-07-28 MCP specification retired the required initialize handshake and Mcp-Session-Id for modern requests. A request is self-describing, so it can land on any healthy replica. Application state is still allowed; the important change is that it should be explicit rather than hidden in the transport.

This repository makes that behavior visible:

1. Nginx sends calls to mcp-a and mcp-b in round-robin order.

2. Each response includes served_by.

3. The workflow survives replica changes because its state travels in request_handle.

4. Nginx logs Mcp-Method, Mcp-Name, and Mcp-Protocol-Version, showing how a gateway can observe and govern tool traffic without parsing the JSON body.

Related MCP server: mcp-stateless-starter

Architecture

sequenceDiagram
    participant C as MCP client
    participant G as Nginx gateway
    participant A as MCP replica A
    participant B as MCP replica B

    C->>G: create_purchase_request
    G->>A: tools/call
    A-->>C: signed request_handle + served_by=mcp-a

    C->>G: add_line_item(request_handle)
    G->>B: tools/call
    B->>B: verify HMAC and decode state
    B-->>C: updated request_handle + served_by=mcp-b

    C->>G: review_purchase_request(request_handle)
    G->>A: tools/call
    A->>A: verify the same explicit state
    A-->>C: summary + served_by=mcp-a

Tools

Run with two replicas

Requirements: Docker and Docker Compose.

cp .env.example .env
# Replace STATE_SIGNING_KEY in .env. For example:
# openssl rand -hex 32

docker compose up --build

The MCP endpoint is:

http://localhost:8080/mcp

In a second terminal, install the project and run the client:

uv sync --dev
uv run python scripts/demo_client.py

Representative output—the exact replica order can vary:

create_purchase_request     replica=mcp-a, total=€0.00
add_line_item (GPU)         replica=mcp-b, total=€450.00
add_line_item (storage)     replica=mcp-a, total=€570.00
review_purchase_request     replica=mcp-b, total=€570.00
submit (without approval)   replica=mcp-a, total=€570.00, status=approval_required
submit (approved)           replica=mcp-b, total=€570.00, status=accepted

Now inspect the gateway logs:

docker compose logs gateway

You should see fields such as:

mcp_method=tools/call mcp_name=add_line_item protocol=2026-07-28 upstream=...

That is the practical value of header-based routing: an API gateway, WAF, or rate limiter can identify the MCP method and tool name directly from headers.

Test with MCP Inspector

The reference Inspector supports modern remote MCP servers:

npx @modelcontextprotocol/inspector --server-url http://localhost:8080/mcp --transport http

Run tests

uv sync --dev
uv run ruff check .
uv run pytest -q

The tests prove that a handle minted by one replica can be verified by another replica with the same key, while tampered, expired, or differently signed handles are rejected.

Important security notes

• The handle is signed, not encrypted. Its contents can be decoded by the client. Never put credentials, secrets, or sensitive personal data in it.

• A real application can return an opaque ID and store state in PostgreSQL, Redis, or another durable system. The MCP transport still remains stateless.

• Tool annotations are behavioral hints, not authorization controls.

• The demo disables SDK DNS-rebinding protection because Nginx controls the inbound Host header locally. A public deployment should configure explicit allowed_hosts and allowed_origins.

• The human_approved field demonstrates a policy checkpoint, not cryptographic proof of a human decision. Production approval should be tied to authenticated identity and authorization.

• The submission is simulated and idempotent; no payment or external order is created.

What this demonstrates

Stateless MCP does not mean “no state.” It means protocol state is not hidden inside a transport session. Once the workflow handle is explicit, the system becomes easier to scale, test, observe, and reason about.

References

• Model Context Protocol 2026-07-28 specification announcement

• Official MCP Python SDK v2 documentation

• Simon Willison, “Stateless MCP has recaptured my interest”

License

MIT