Home · Guides

Return a handle, because there is no session to hang state on

A server that needs one tool call to know about another cannot rely on the connection to carry it. The MCP specification is direct about this in its guidance on stateful tools, revision 2026-07-28:

The protocol has no concept of a state handle; from the wire's perspective a handle is an ordinary string in a tool result and an ordinary argument to subsequent tool calls.

And on why implicit state is not available: MCP has no protocol-level session, so a server cannot relate one tool call to the next through the connection. Revision 2026-07-28 removed protocol-level sessions from the streamable HTTP binding, so this is not a gap waiting to be filled.

The pattern

A creation tool returns an identifier. Every later tool takes it as an argument. The model is responsible for carrying it forward, which it does well because the identifier is right there in the previous result.

// tools/call
{ "name": "create_basket", "arguments": {} }

// result
{ "content": [{ "type": "text", "text": "Created basket bsk_a1b2c3" }],
  "structuredContent": { "basket_id": "bsk_a1b2c3" } }

// tools/call
{ "name": "add_item", "arguments": { "basket_id": "bsk_a1b2c3", "sku": "..." } }

Put the handle in both places. structuredContent is what a client can extract mechanically, and the text block is what an older client and the model both read.

The four things the specification tells you to decide

Authorization. For an authenticated server a handle is a name, not a capability, so validate the caller against the handle on every call. For an unauthenticated server the handle is necessarily a bearer token, which means enough entropy to be unguessable and a bounded lifetime.
Opacity. A handle that encodes internal structure invites parsing and guessing. Opaque identifiers do not.
Lifetime. Handles outlive any single connection, so state the retention policy in the creation tool's description, for example that baskets expire after 24 hours of inactivity. The model sees that text when it decides whether to create state.
Expiry errors. A call against an expired or unknown handle should return a tool execution error saying so, not a protocol error, so the model can recover by creating a new one.

Point four is where most implementations go wrong, and it connects to the two error channels: a thrown exception becomes a JSON-RPC error, which clients are only told they MAY pass to the model.

What this looks like on a hosted server

A remote MCP server has a second problem the local case does not: the handle has to identify a tenant as well as a document. This project's hosted endpoints solve it with a token rather than a per-tool handle. The token arrives in the Authorization header or, for clients that can only accept a URL, as a path segment, and it is the key that every stored document hangs from.

https://mcp.zovo.one/mcp/<server>/t/<token>

The trade is worth naming. A token in a URL is visible in logs and in anything that records the configuration, which is why it grants only a free anonymous tier here. Where a client can set headers, the header is the right place. Where it cannot, the URL form is the difference between working and not.

When not to use a handle at all

If every call can carry the whole input, do that. Handles add a lifetime, an authorization check and a failure mode, and a model that loses track of one produces a confusing conversation. They earn their place when the state is large, expensive to rebuild, or genuinely shared, such as an open browser context or a transaction. They do not earn it as a way to avoid repeating a filename.

Source: the stateful tools section of the MCP specification, revision 2026-07-28, at modelcontextprotocol.io, fetched 2026-09-09, which is explicitly non-normative guidance rather than a requirement. The example payloads are the specification's own. The hosted token form is this project's implementation, live at mcp.zovo.one on every hosted endpoint.

Questions

What happened to session IDs in streamable HTTP?

Protocol-level sessions were removed in revision 2026-07-28, along with the standalone GET stream. A server that still wants per-connection continuity has to build it from something it controls, such as a token or a handle in the arguments.

Can I use the token as the handle?

For tenancy, yes, and that is what a hosted server usually does. For a short-lived object such as a cart or a transaction you still want a separate handle, because its lifetime is different and you will want to expire it without invalidating the tenant.

How long should a handle live?

Long enough to survive a conversation and short enough that an abandoned one costs nothing, and whatever you choose belongs in the creation tool's description. The specification's example wording is that baskets expire after 24 hours of inactivity.

Will the model actually carry the handle forward?

Usually, if it is visible in the result text and the argument that needs it is described clearly. Naming the parameter the same thing as the field you returned helps more than any instruction in the description.

Is a sequential integer an acceptable handle?

Only on an authenticated server that checks ownership on every call. On an unauthenticated one the handle is a bearer token, and a sequential integer is guessable by design, which the specification calls out directly.

All MCP servers and prices · All guides · Buy the bundle $39