Migrating tool hosts for stateless model context integrations

Migrating tool hosts for stateless model context integrations is not a simple transport upgrade. It changes where a platform draws the boundary between protocol delivery, application continuity, model context, authorization, and orchestration. For teams running specialist agents through an MCP-connected control plane, that boundary determines whether a deployment can scale cleanly, survive instance turnover, preserve approvals, and keep tool access governable.

The MCP 2026-07-28 specification release moves the protocol core from a bidirectional, sessionful model to request/response over ordinary HTTP infrastructure. That enables routing, caching, and horizontal scaling without making a transport session the hidden source of truth. The practical consequence is not that all state disappears. It is that durable state must be designed deliberately, surfaced in application data, and owned by the components that actually need it: hosts, workflow services, identity systems, caches, and domain backends.

Understand what is changing,and what is not

In a sessionful design, a tool host or server can quietly rely on a long-lived connection to preserve assumptions: which user is active, which model request started a workflow, what an elicitation callback expects, or which in-memory object represents an unfinished operation. That can work in a small deployment, but it couples correctness to connection affinity and process lifetime.

The stateless MCP model changes the transport contract. The release candidate describes remote MCP servers operating behind a plain round-robin load balancer because every request is self-describing and can reach any healthy instance. For many tool-host deployments, sticky sessions are no longer a protocol requirement.

Stateless transport is not stateless product behavior. It is a requirement to make product behavior explicit enough that any healthy request handler can continue the work safely.

This distinction is especially important in an AI agent orchestration workspace. The host still owns the model, the conversation, tool registration, approval experience, and connection lifecycle. What becomes narrower is the transport’s job: it no longer needs to preserve the host’s implicit session state in order for requests to make progress.

Separate the layers before planning the migration

A reliable migration starts by identifying the layer where each piece of state belongs. Treating all state as “MCP session state” makes the old architecture difficult to reason about and makes the new architecture appear more disruptive than it is.

• Protocol transport state

  covers request delivery and response handling. Under the new stateless wire format, it should not be the location of durable workflow facts.

• Host and conversation state

  includes model messages, agent handoffs, user approvals, policy decisions, and selected tools. A host may retain or retrieve this state, but it should do so through explicit application mechanisms.

• Tool domain state

  includes jobs, transactions, cursors, exports, drafts, and long-running operations. It should live in the relevant service or durable store and be referenced by an explicit identifier.

• Operational state

  includes cache entries, request correlation, rate-limit counters, authorization context, and telemetry. These concerns need clear lifetimes and ownership, but do not need a sticky MCP connection.

Recent MCP architecture research similarly reinforces that protocol transport and application state are different concerns. That is a useful design test: if a tool call would fail simply because a load balancer sent the next request to another instance, the application has probably left necessary state in the wrong layer.

Inventory hidden session dependencies before moving traffic

Most migration risk comes from dependencies that are not labeled as session state. They often appear as convenience features: per-connection dictionaries, callback registries, event-stream stores, local job references, or middleware that assumes the same process will see the next request. An inventory should find these dependencies before a host is switched to stateless handling.

Start from the request paths that matter to users, not only from the server initialization code. Follow a tool invocation through authorization, model orchestration, approval handling, backend calls, and result delivery. Then ask what must still be available when the next request lands on a different process, node, or region.

Find assumptions in the host

Host code is often where hidden coupling accumulates. A host may use an in-memory conversation object to resolve a tool result, preserve a selected specialist agent in a connection-local variable, or keep pending approvals in a callback map. Those patterns are not automatically invalid, but they must be replaced with an explicit key and durable or shared retrieval path if another instance needs to continue them.

1. Map inbound identity.

   Record how the host derives tenant, user, client, conversation, and agent-run identity for every tool call.

2. Map outbound continuity.

   Identify every value expected to come back later: a job identifier, approval decision, pagination cursor, resource reference, model sampling response, or tool execution result.

3. Classify the lifetime.

   Decide whether each value lasts only for one request, for a multi-turn workflow, for a conversation, or for a domain-defined retention period.

4. Assign an owner.

   Put durable facts in a service or store that can be reached from any host instance. Keep only request-scoped objects in local memory.

5. Test an instance change.

   Force a follow-up request to hit another instance. If the flow fails, identify the missing explicit state or contract.

Use SDK migration signals as code-review clues

SDK guidance provides concrete indicators of the old model. In the C# SDK migration guidance, session-oriented knobs such as IdleTimeout, MaxIdleSessionCount, EventStreamStore, SessionMigrationHandler, and PerSessionExecutionContext are marked obsolete for the new stateless wire format. Their presence in a deployment is a strong signal to inspect how the system currently preserves continuity.

The same principle applies outside C#. The Go SDK exposes StreamableHTTPOptions.Stateless, and its documentation states that streamable HTTP for 2026-07-28 requires Stateless = true. TypeScript SDK v2 uses a createMcpHandler(factory) entrypoint that serves 2026-07-28 per request and follows the stateless idiom by default. These are implementation details, but they reflect the architectural shift: handler construction and state access must be safe for independently routed requests.

Do not interpret an SDK flag as the entire migration. Enabling stateless mode while retaining a process-local approval registry or a connection-bound workflow object merely moves the failure from the protocol layer to the application layer.

Replace implicit continuity with explicit handles

The specification’s primary pattern for continuity is straightforward: when a server needs state across calls, a tool mints an explicit handle and the model passes that handle back as a later tool argument. This makes the dependency inspectable, loggable, authorizable, and routable. It also allows any healthy instance to resolve the state, instead of requiring the original connection or process.

Handles should represent a domain concept rather than an accidental server-memory address. Examples include an import operation, a report draft, a transaction preparation, a search cursor, an approval request, or a workflow run. The handle is not necessarily the state itself; it is a reference to state owned by the correct backend.

Design handles as security boundaries

A handle must not become an ungoverned bearer token. When a tool receives one, it should validate that the requester is allowed to access the referenced object in the current tenant and workflow context. Depending on the design, the handle may be opaque, signed, or backed by a durable record, but authorization should not rely on the handle alone.

Useful handle contracts are intentionally small. Return only what the caller needs to continue, include stable semantics in tool documentation, and define invalidation behavior. If a handle can expire, say so. If an operation is idempotent, expose the idempotency mechanism instead of relying on a repeated request reaching the same instance.

• Create:

  start_export

  returns an

  export_handle

  and a clear next action.

• Continue:

  get_export_status

  accepts the handle and returns current

  durable state

  from any instance.

• Finalize:

  download_export

  or

  cancel_export

  accepts the same handle and evaluates current authorization.

• Audit:

  each operation records the host, principal, tenant, tool identity, handle reference, and policy outcome without logging unnecessary sensitive content.

This pattern improves more than scalability. It makes agent handoffs safer because a specialist agent can receive a constrained, documented reference instead of inheriting an opaque connection context. It also makes support and incident analysis easier: operators can identify exactly which workflow object was touched rather than trying to reconstruct a connection-local history.

Do not overload conversation history

A model conversation may contain a handle, but the conversation transcript is not a durable workflow database. Hosts should preserve model context according to their product needs while keeping operational truth in the service that owns it. For example, an agent may remember that an export was requested, while the export service remains authoritative on whether the export exists, is ready, has been cancelled, or can be downloaded.

This boundary matters when conversations are summarized, transferred between specialist agents, replayed, or subject to retention controls. Explicit handles allow the host to pass the minimum necessary continuity through the model context while resolving sensitive or volatile details only at tool execution time.

Use cacheable discovery and er-based routing deliberately

Stateless HTTP creates a stronger opportunity to use ordinary infrastructure well. The updated protocol allows tools/list, prompts/list, resources/list, and resources/read to carry cache hints through ttlMs and cacheScope, with deterministic ordering. Hosts can reduce repeated discovery fetches and keep prompt caches more stable when catalogs are treated as cacheable control-plane data.

That does not mean every catalog should be cached identically. A global tool catalog, a tenant-specific catalog, and a user-scoped catalog have different correctness and security requirements. Cache scope should reflect the actual audience of the data, and a host should invalidate or refresh entries when policy, entitlement, or capability changes require it.

Build a discovery path, not a one-time assumption

Capability discovery should be an active part of host behavior. At connection or registration time, the host can obtain the tools, prompts, and resources available to a particular integration. It can then curate that surface for the agent and user context rather than exposing every discovered capability to every model turn.

Curating matters for model reliability as well as governance. Recent systems research reports tool-selection accuracy dropping below 90% at roughly 10,15 tools for one model family and 20,30 tools for another. Those findings do not establish a universal limit, but they support a pragmatic host design: present a focused set of tools relevant to the task, route to specialist agents where appropriate, and avoid treating a large unfiltered catalog as a usability feature.

A cache-aware host can therefore maintain a versioned internal view of tool availability while applying dynamic policy at invocation time. Cache the catalog when appropriate; do not cache an authorization decision beyond the point where it remains valid.

Route with declared identity, not inspection

The specification moves method and tool identity into HTTP ers for streamable HTTP requests through Mcp-Method and Mcp-Name. This lets gateways route, meter, and authorize requests without parsing request bodies. For platform teams, that enables cleaner integration with API gateways, observability systems, and policy enforcement points.

A gateway can use these ers to send a tool call to the correct server pool, apply a tool-level rate limit, attach tracing metadata, or reject access before a backend spends resources decoding a payload. The gateway should still treat ers as inputs that must be validated in the context of the request. Routing identity is useful, but it does not replace end-to-end authorization in the host and tool service.

1. Define routing ownership for each method and tool name.

2. Set rate limits and telemetry dimensions that align with that ownership.

3. Evaluate tenant, principal, client, and policy context before dispatching sensitive tools.

4. Ensure backend authorization verifies the same domain boundaries rather than trusting an upstream routing decision alone.

5. Monitor unknown, deprecated, and unexpectedly high-volume method or tool names as migration signals.

Redesign sampling, elicitation, and approvals around MRTR

Some of the hardest session migrations occur in server-to-client interactions. Older held-open stream patterns encouraged implementations to keep callback paths and pending interaction state tied to a connection. The redesigned approach uses Multi Round-Trip Requests, or MRTR, for flows such as elicitation and sampling, allowing back-and-forth interactions without protocol-level sessions.

For a host, the key operational question is no longer “which stream is still open?” It is “what request is this interaction continuing, who is allowed to answer it, and what state must be retrieved to process the answer safely?” That is a better question for resilient systems because it forces the workflow identity and approval context into durable application data.

Model the interaction as a workflow state machine

A practical design records an interaction record when a tool or agent needs input, sampling, or human approval. The record should identify the workflow or agent run, expected response type, requesting tool, relevant tenant and principal context, expiration policy, and current status. A later request references the interaction explicitly and can be handled by any healthy host instance.

This is particularly useful for enterprise approval UX. A user may approve an action from a web application, an operations console, or another supported host interface after the original tool call has completed. The approval decision should be bound to the operation being approved and rechecked against current policy, not accepted merely because it arrived on the original connection.

Python migration guidance illustrates why this deserves explicit testing. Its v1-to-v2 guidance warns that unchanged v1 sampling and elicitation workflows can fail when the client negotiates 2026-07-28 by default, because no request reaches the prior client-side callback path. Teams should treat this as an application-flow migration, not as a routine dependency update.

Test failure paths as carefully as happy paths

For each MRTR-based interaction, test restart, timeout, duplicate delivery, user cancellation, authorization change, and an instance change between every round trip. Test what the model sees when an interaction expires and what operators see when a human approval cannot be matched to a valid workflow.

• Use explicit interaction identifiers instead of connection-local callbacks.

• Make response handling idempotent where duplicate submissions are possible.

• Bind approvals to an operation, principal, tenant, and policy context.

• Define timeout and cancellation behavior in the tool contract.

• Log correlation identifiers across host, gateway, workflow service, and tool backend.

These controls preserve a good user experience without pretending the transport is the workflow engine. They also support multi-agent orchestration, where an agent can request an approval and a later specialist agent can continue only after the host verifies that the approval is valid for the current action.

Run old and new clients through a controlled compatibility period

A stateless migration does not require an all-at-once client cutover. The release candidate explicitly formalizes a path in which implementers can support 2025-11-25-era traffic while serving 2026-07-28 statelessly on the same endpoint. This lowers the operational risk of moving hosts, servers, and SDK versions at different times.

The specification also introduces a formal deprecation policy with a twelve-month minimum window. That provides planning room, but it should not be used as a reason to postpone architecture work. A compatibility window is most valuable when it has exit criteria, measurable adoption, and a clear reduction of legacy-only behavior.

Choose an endpoint strategy that keeps semantics clear

Serving compatible traffic from one endpoint can simplify network and client configuration, provided the server’s behavior remains unambiguous. Do not let support for an older wire format create two unrelated authorization models or two different definitions of the same tool. The tool contract, policy enforcement, audit requirements, and domain state should remain consistent even if protocol negotiation differs.

Some SDKs make the target model visible. C# documentation says HTTP transport does not assign Mcp-Session-Id or track session state in memory by default. TypeScript SDK v2 can serve the new specification per request through createMcpHandler(factory) while also serving older traffic through the stateless idiom by default. PHP documentation includes a stateless-lifecycle example that pins 2026-07-28, skips the handshake, uses server/discover, and calls tools in one process without a session.

These examples should guide test design rather than dictate a single stack. Confirm what version each deployed client negotiates, what features it uses, and whether it contains assumptions about handshakes, sessions, callbacks, or streams.

Use progressive migration gates

1. Establish a baseline.

   Measure current tool success paths, discovery behavior, authorization denials, latency patterns, and connection-related failures before changing production traffic.

2. Make state explicit first.

   Remove process-local continuity dependencies and validate that a request can be served after a handler restart.

3. Enable stateless handling in a non-production environment.

   Exercise discovery, tools, resources, prompts, sampling, elicitation, and approval workflows.

4. Canary by client or tenant.

   Route a small compatible population through the new handling path while preserving clear rollback controls.

5. Observe legacy usage.

   Track negotiated versions and legacy-only paths so the team knows when compatibility can be retired.

6. Remove obsolete session infrastructure.

   Decommission stores, affinity rules, and code paths only after evidence shows they are no longer required.

Cloudflare’s MCP transport documentation also notes that there is no protocol-level session on the stateless path and directs implementers to staged SDK migration guidance. The broader lesson is consistent: deployment sequencing matters because the host, SDK, gateway, and workflow implementation may not move at the same time.

Strengthen trust, authorization, and tool governance

Stateless routing makes it easier to scale tool access, but it also makes policy boundaries more visible. The 2026 specification release highlights authorization hardening, including iss validation and a shift away from Dynamic Client Registration toward client metadata documents. Platform teams should treat these changes as part of the migration’s security work, not as optional cleanup after traffic is moved.

Host-side governance remains essential because the protocol does not decide which servers a host should use or at what sensitivity. A recent arXiv paper argues that MCP host-side trust is still under-specified: hosts read a server’s self-declared tool list and dispatch calls, but the protocol itself does not make the trust decision. In practice, the host must supply that decision through an integration registry, policy model, approval controls, and ongoing review.

Establish a trustworthy server admission process

Do not automatically elevate a discovered tool list into an agent-accessible capability set. An enterprise host should know who owns the server, what tenant and data boundaries it supports, which tools are approved, what data each tool can access, and what conditions require a user approval or a specialist agent.

• Maintain an allowlist or governed registry of approved MCP servers and tool identities.

• Review declared tools for scope, input expectations, side effects, and data sensitivity.

• Map each tool to an authorization policy, audit requirement, rate limit, and owner.

• Expose only task-relevant tools to a given agent run or user context.

• Require appropriate approval UX for consequential actions, even when a model can invoke the tool directly.

• Revalidate authorization at execution time, especially for explicit handles that may outlive a prior session or conversation turn.

Header-based method and tool identity can help a gateway apply controls earlier, while the host continues to apply context-aware policy. This layered approach is more reliable than choosing between central gateway enforcement and backend enforcement. The gateway can stop obviously unauthorized or excessive traffic; the host and tool service can enforce the domain semantics that only they understand.

Preserve auditability across agent handoffs

In a multi-agent workspace, a handoff should not erase accountability. Record which host selected the tool, which specialist agent recommended or executed the action, what user or service principal authorized it, and what explicit workflow handle was involved. The record should support operational investigation without indiscriminately storing sensitive prompts or tool payloads.

Trustworthiness also requires honest failure behavior. If a handle cannot be resolved, an approval has expired, a capability is no longer available, or a policy changed after an agent planned an action, return a clear structured outcome. Do not recreate missing state from guessed conversation context or silently route to an unreviewed fallback tool.

Operate stateless hosts with end-to-end observability

Horizontal scaling is one of the clearest benefits of a stateless tool host, but it is only safe when operators can trace work across independently routed requests. The host should emit correlation data that connects a model turn, agent run, tool call, workflow handle, authorization decision, backend operation, and final result. The identifiers should be purposeful: enough to reconstruct a transaction, but not a substitute for logging all sensitive content.

Operational design also needs to distinguish protocol statelessness from the broader statefulness of AI serving. A 2026 simulator paper on multi-turn agent serving models program identity, turn order, tool-induced gaps, and KV residency across memory tiers. Its implication for platform architecture is practical: eliminating a protocol session does not eliminate model-context caching, workflow scheduling, or memory-placement decisions.

Measure the migration at the right boundaries

Instrument the path between host and tool server, but do not stop there. A request can be stateless and still experience a degraded user journey if catalog caches are stale, an approval lookup is slow, a workflow store is unavailable, or an agent receives too many irrelevant tools.

Useful indicators include:

• Tool invocation success and failure by

  Mcp-Method

  ,

  Mcp-Name

  , server, tenant, and policy outcome.

• Discovery cache hit behavior, refresh failures, and catalog version changes.

• Explicit handle creation, resolution, expiration, invalid access, and duplicate-operation events.

• MRTR interaction completion, timeout, cancellation, and approval rejection paths.

• Request distribution across instances, including evidence that follow-up calls succeed after an instance change.

• Legacy protocol usage during the compatibility period and the remaining dependencies that prevent retirement.

Design for ordinary infrastructure failures

Stateless handling should make a server pool more resilient to individual instance loss, but dependency failures still require deliberate behavior. Use timeouts, retries only where safe, idempotency protections for side-effecting operations, and clear degradation policies for discovery or workflow-state dependencies. A round-robin load balancer cannot correct a tool contract that repeats a destructive operation when a response is lost.

Cache-aware routing is also important at the host layer. Tool-induced gaps and multi-turn workflows may interact with model context and cache residency even when MCP messages are individually routable. Keep the orchestration policy explicit: decide when a model context should be retained, summarized, handed off, or recomputed, and do not confuse that decision with an old requirement for transport affinity.

Finally, practice recovery. Restart a host instance during an active workflow, route the next request to another instance, invalidate a discovery cache, revoke a tool entitlement, and submit an expired approval. A migration is complete only when the expected outcomes are predictable and observable under those conditions.

Adopt a practical target architecture

A mature stateless integration usually has a small number of clear responsibilities. The gateway receives ordinary HTTP traffic and uses declared method and tool identity for routing, metering, and preliminary enforcement. The host manages model context, agent selection, tool registration, approvals, and orchestration. The tool server processes self-describing requests and obtains durable domain state through explicit handles. Shared services provide identity, policy, workflow persistence, catalog caching, and telemetry.

This target is intentionally not a claim that every interaction must become remote or every state store must be centralized. Some request-scoped work belongs in memory, and some low-latency deployments may use local caches. The requirement is that correctness does not depend on a particular transport session or a specific handler receiving the next request.

Use this decision rule for every design choice

Ask whether another healthy instance can process the next request using only the request, authorized shared data, and documented cacheable metadata. If the answer is no, either mint an explicit handle, move durable state to its owning service, or redesign the workflow boundary. If the answer is yes, the deployment is aligned with the core advantage of stateless MCP: ordinary infrastructure can scale and recover without carrying hidden conversational transport state.

For platform engineers, the migration is therefore an opportunity to improve the entire tool integration lifecycle. It encourages narrower tool surfaces, cleaner agent handoffs, stronger policy enforcement, more predictable approvals, cache-aware discovery, and a clearer separation between model context and domain truth. Those are useful outcomes even before a load balancer sends the first request to a different instance.

Stateless MCP does not reduce the importance of hosts. It makes their responsibilities more explicit: own the model and user experience, curate trusted capabilities, carry the right context between specialist agents, and enforce approvals and policy at the point of action. Tool servers can then focus on serving self-describing requests against durable application state, rather than maintaining hidden session continuity.

The safest migration path is incremental and evidence-driven. Inventory session assumptions, introduce explicit handles, validate MRTR workflows, apply cache and routing controls, support older clients during a managed transition, and measure behavior across host, gateway, and backend boundaries. With that approach, a stateless model context integration becomes not merely easier to scale, but easier to operate, secure, and evolve.