Design stateful MCP tools with explicit handles now that the protocol has no session (2026-07-28)

Documented steps

1. Start from the constraint: MCP has no protocol-level session, so a server cannot rely on implicit per-connection state to relate one tool call to the next.
2. Model the state explicitly. Expose a creation tool that returns a handle — a shopping basket id, a browser context id, a transaction id — in both a text content block and structuredContent.
3. Accept that handle as an ordinary argument on every subsequent tool call, e.g. create_basket() returns {"basket_id":"bsk_a1b2c3"} and add_item takes {"basket_id":"bsk_a1b2c3", "sku":"..."}.
4. Store the state server-side keyed by the handle, and let the model carry the handle forward in its context.
5. For authenticated servers, treat the handle as a NAME, not a capability: validate the caller's authorization against the handle on every call. Key stored state by the authenticated principal plus the handle (e.g. <user_id>:<handle>) using the user id from the verified token, never a client-asserted identity.
6. For unauthenticated servers, where the handle is necessarily a bearer token, generate it with sufficient entropy (e.g. UUIDv4) and give it a bounded lifetime.
7. Keep handles opaque — identifiers that encode internal structure invite parsing and guessing.
8. State the retention policy in the creation tool's DESCRIPTION (e.g. 'baskets expire after 24 hours of inactivity') so the model can see it when deciding to create state.
9. Return a tool execution error (isError: true) with a clear message for a call against an expired or unknown handle, so the model can recover by creating a new one.
10. Cross-check the Stateful Tools guidance at https://modelcontextprotocol.io/specification/2026-07-28/server/tools and State Handle Hijacking at https://modelcontextprotocol.io/docs/2026-07-28/tutorials/security/security_best_practices