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

Sources: Spec · Changelog · Blog

Related MCP server: Mock MCP Server

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

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

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