MCP Stateless Examples

Educational implementation of the MCP 2026-07-28 stateless protocol — the largest revision since launch, finalized July 28, 2026.

Built with raw Starlette (no SDK dependency) to show the wire protocol clearly. Supply-chain hardened throughout.

What's New in 2026-07-28

Change	Impact
Stateless core	No initialize handshake, no Mcp-Session-Id
_meta envelope	Every request carries protocolVersion + clientCapabilities
server/discover	Replaces initialize for capability discovery
Routing headers	Mcp-Method + Mcp-Name required on all POSTs
MRTR	InputRequiredResult replaces server→client SSE requests
requestState	HMAC-signed opaque handle for multi-round state
subscriptions/listen	Long-lived POST→SSE replaces GET endpoint

Sources: Spec · Changelog · Blog

Quick Start

# Install
pip install -e ".[dev]"

# Run the server
uvicorn mcp_stateless.server:app --reload

# In another terminal, try the examples
python examples/01_basic_tool.py
python examples/02_state_handle.py
python examples/03_mrtr_elicitation.py

# Or use curl
bash examples/curl/discover.sh
bash examples/curl/tools_list.sh
bash examples/curl/tools_call.sh

Examples

#	Example	Pattern
01	Basic tool call	Simplest stateless tools/call
02	State handle	Server-minted handle for cross-request state
03	MRTR elicitation	Multi-round with user input
04	MRTR sampling	Multi-round with LLM sampling + decline path
05	Subscriptions	subscriptions/listen change notifications
06	Dual-era sketch	Backward compat with 2025-era clients

Architecture

src/mcp_stateless/
├── server.py          # Starlette app, JSON-RPC routing
├── meta.py            # _meta envelope parsing + validation
├── headers.py         # MCP-Protocol-Version, Mcp-Method, Mcp-Name, Origin
├── discover.py        # server/discover RPC
├── request_state.py   # HMAC-SHA256 requestState codec
├── mrtr.py            # InputRequiredResult + inputResponses helpers
└── tools/
    ├── __init__.py    # SENTINEL-TPD tool registry + scanning
    ├── weather.py     # Stateless tool (no state)
    ├── cart.py        # Stateful-via-handle tool
    └── brainstorm.py  # MRTR multi-round tool

Security

• SENTINEL-TPD: Tool descriptions scanned at registration for poisoning signals
• Origin validation: DNS rebinding defense
• Header-body validation: Prevents routing spoofing
• State handle security: HMAC-signed, principal-bound, TTL-expiring
• Capability enforcement: Server rejects undeclared client capabilities

See docs/security-model.md for the full threat model.

Supply Chain

Control	Status
Wolfi/distroless base	Dockerfile with pinning notes
SBOM (syft)	CI workflow
cosign signing	supply-chain.yml
SLSA Level 3	slsa-github-generator
Pinned deps	pyproject.toml
Non-root container	UID 1000

bash scripts/verify_supply_chain.sh

Testing

python -m pytest tests/ -v

Test coverage:

• _meta envelope parsing and validation
• Header mismatch detection (all required headers)
• requestState HMAC codec (mint, verify, tamper, expiry, principal binding)
• MRTR helpers (InputRequiredResult, inputResponses)
• SENTINEL-TPD tool scanning (poisoning detection, quarantine)
• Stateless invariants (no session, no initialize, per-request _meta)

License

MIT