Blog · · 10 min read

Migrate MCP Sampling without breaking agent workflows

Migrate MCP Sampling without breaking agent workflows

MCP Sampling used to let a server ask its client to run a model in the middle of a tool workflow. The 2026-07-28 protocol no longer supports that pushed server request. It uses Multi Round-Trip Requests, or MRTR, and SDKs deprecate Sampling for new implementations. A partial migration can break older hosts, repeat model rounds, lose cancellation, or replay the enclosing product action.

Do not replace one callback with another and call the migration complete. First decide who should own model access. Then put modern MRTR and legacy behavior behind one product contract, limit every round, preserve workflow identity, and prove both paths produce the same safe outcome before deleting the old one.

Understand what changed

The MCP 2026-07-28 MRTR specification replaces server-initiated requests such as sampling/createMessage, roots/list, and elicitation/create. A modern server ends the current round with resultType: "input_required". The client fulfills each item in inputRequests, then retries the original tools/call, resources/read, or prompts/get request with inputResponses and any opaque requestState.

The first request is over. The retry has a new JSON-RPC request ID, and another server instance may receive it. Any state required to continue must be present in protected requestState or stored under a durable product operation ID.

The official changelog also requires every result to carry a resultType. Modern clients must treat older results that omit the field as complete. That compatibility rule helps clients read old responses, but it does not make an old server-initiated callback valid on a modern connection.

Tier 1 SDK guidance adds a second distinction. The TypeScript client documentation says servers should call an LLM provider directly instead of using Sampling, while retaining a Sampling handler for servers that have not migrated. The Python SDK deprecation guide documents MRTR as the protocol replacement and keeps explicit legacy mode for connections that negotiated 2025-11-25 or earlier.

Choose among three paths:

  1. Direct provider integration for new server-owned model work.
  2. MRTR carrying a CreateMessageRequest when the client must retain control of model access.
  3. A bounded legacy sampling/createMessage adapter for old protocol sessions during migration.

Choose the target architecture before changing code

Start with ownership. Ask why the server requests Sampling.

Use a direct provider call when the product service owns the model account, model policy, cost, retention rules, and observability. This path removes an avoidable client callback and matches the TypeScript SDK recommendation. It also makes provider errors, budgets, and model selection visible to the service that owns the workflow. Choosing MRTR because it is the protocol's own replacement for Sampling is the wrong default for that case, because it hands the model run to a client the server does not control and gives up the budget, model policy, and error visibility the direct path keeps.

Use an MRTR input request only when the host must choose or run the model. Examples include a desktop host that supplies the user's configured provider, an enterprise client that applies its own model policy, or a platform where the server is intentionally provider-neutral. The server returns an InputRequiredResult; the client fulfills the embedded CreateMessageRequest; and the client retries the original operation.

Keep legacy Sampling only as a compatibility path. Give it an owner, a measured usage counter, and a removal date. Do not let new code select it merely because a callback already exists.

Write the decision as code rather than scattered version checks:

type SamplingPath = "direct" | "mrtr" | "legacy" | "unsupported";

function selectSamplingPath(input: {
  protocolVersion: string;
  clientSupportsSampling: boolean;
  serverOwnsModelAccess: boolean;
}): SamplingPath {
  if (input.serverOwnsModelAccess) return "direct";
  if (input.protocolVersion === "2026-07-28" && input.clientSupportsSampling) {
    return "mrtr";
  }
  if (input.protocolVersion <= "2025-11-25" && input.clientSupportsSampling) {
    return "legacy";
  }
  return "unsupported";
}

A real version comparison should use your SDK's negotiated protocol representation, not lexical string ordering. Keep the decision explicit, logged, and testable.

Inventory the existing Sampling surface

Search the server, clients, gateways, and tests for more than sampling/createMessage. Include SDK helpers such as requestSampling, create_message, sampling_callback, and request handlers. Trace each call back to the product operation that triggered it.

Record these fields for every use:

  • enclosing MCP method and tool name;
  • whether the server or client owns model access;
  • message and system-prompt source;
  • allowed model and token budget;
  • whether the model may request tools;
  • maximum nested rounds;
  • cancellation and timeout behavior;
  • product side effects before and after Sampling;
  • protocol versions and clients observed in production;
  • evidence used to mark the operation complete.

Flag any flow that performs an irreversible action before Sampling returns. A retry can re-enter that code. Move the side effect behind an idempotent commit boundary or record an authoritative receipt before the protocol migration begins.

Also inspect multi-round history handling. Pydantic AI issue #7707 reports a Sampling flow that worked in the first round but failed after tool calls because the next model request did not retain the required tool-call history. Treat that as a reproducible failure class: every model turn, tool request, and tool result must be carried in valid order or reconstructed from durable state.

Put all paths behind one operation contract

The compatibility layer should translate protocol mechanics into one internal result. Product code should not care whether a model response came from a direct provider call, an MRTR retry, or a legacy callback.

type ModelStepResult =
  | { kind: "complete"; output: unknown; receiptId: string }
  | { kind: "input_required"; requestState: string }
  | { kind: "cancelled"; reason: string }
  | { kind: "failed"; retryable: boolean; code: string };

type SamplingOperation = {
  operationId: string;
  tenantId: string;
  principalId: string;
  releaseId: string;
  path: "direct" | "mrtr" | "legacy";
  round: number;
  maxRounds: number;
  deadline: string;
  promptDigest: string;
  status: "running" | "waiting" | "complete" | "cancelled" | "failed";
};

Persist or integrity-protect the fields needed on retry. The MRTR specification treats requestState as attacker-controlled input. If it affects authorization, resource access, or business logic, protect it with an HMAC or authenticated encryption. Bind it to the authenticated principal, the originating method and salient parameters, and a short expiry. A protected token limits tampering and cross-user replay, but it does not enforce single use. Keep server-side consumption state when one response must be accepted at most once.

Use stable server-assigned keys inside inputRequests. They only need to be unique within the request, but stable semantic names make traces and tests easier to interpret. Map each key to one expected response and reject missing, duplicate, unexpected, or type-invalid entries before continuing.

Implement the migration in seven steps

1. Add protocol and capability probes

Centralize protocol selection at the transport boundary. Modern requests carry protocol version and client capabilities in _meta; legacy sessions use their negotiated connection state. Return a typed unsupported result when a client cannot fulfill host-controlled model work. Do not send a Sampling request and wait for a timeout as capability detection.

2. Build the direct provider path

Move model invocation into a service with explicit model allowlists, token limits, deadlines, cost attribution, and provider error mapping. Preserve the old callback's intended model policy without copying client credentials into the server. If the server cannot obtain appropriately scoped provider access, direct invocation is not the right path.

3. Build the MRTR adapter

On a modern connection, return resultType: "input_required" with a CreateMessageRequest in inputRequests. Include protected requestState or a durable operation handle. When the client retries the original request, validate inputResponses, reload the operation, increment the round atomically, and continue from the waiting checkpoint.

The first handler invocation must not remain open while the client runs the model. MRTR was designed so the retry can reach another server instance without shared connection state.

4. Isolate the legacy callback

Keep sampling/createMessage registration in one adapter used only by eligible legacy sessions. The TypeScript SDK says one handler can serve both pushed and SDK-fulfilled requests, but your product still needs to record which delivery path ran. Without that field, legacy usage cannot be measured or removed safely.

Older bidirectional implementations also need request-ID collision tests. Terfyn issue #397 reports client and server counters producing the same JSON-RPC ID, which caused a server-initiated request to reach the wrong pending handler. Use a transport implementation that separates or safely dispatches both request directions, and test overlapping IDs before keeping legacy support enabled.

5. Bound every automatic round

A client may automatically fulfill MRTR input requests and retry the original call. The TypeScript SDK exposes inputRequired.maxRounds; its documented default is 10, and it can disable automatic fulfillment entirely with autoFulfill: false.

Set a lower product-specific cap. Count direct provider loops, MRTR retries, and legacy callbacks against the same operation budget. Stop with a typed failure that names the exhausted budget. Do not reset the counter when transport retries, server replicas, or protocol adapters change.

6. Propagate cancellation and deadlines

Cancellation belongs to the product operation, not one request object. When the user cancels, mark the durable operation first, then abort any active provider call or callback. Every retry and response handler must recheck that terminal state before using a model result or calling a tool.

Use one deadline across all rounds. A fresh JSON-RPC request ID does not earn a fresh business deadline. Late model responses should be retained only as diagnostic evidence and must not revive a cancelled or expired operation.

7. Verify outcomes before completion

Compare authoritative product state as well as model text. If a model result leads to a tool call, bind that action to a stable operation and action ID. Reuse an existing receipt on retry. Return complete only after the required postcondition holds.

Otherwise, both protocol paths can return plausible text while one silently skipped a tool result or repeated a side effect.

Roll out with a compatibility matrix

Test at least four combinations:

  • modern client with direct provider execution;
  • modern client with MRTR host-controlled execution;
  • legacy client with the pushed Sampling adapter;
  • unsupported client with a deterministic, actionable failure.

For each combination, run single-round completion, multiple model rounds, a tool call between model turns, client cancellation, provider timeout, malformed input, expired state, repeated retry, different server replica, and a disconnect before the retry. Verify final product state and side-effect receipts after every case.

Use shadow comparison before switching writes. Execute the candidate path against read-only fixtures or controlled tools, then compare normalized model intent, requested tools, policy decisions, round counts, latency, cost, and final postconditions. Do not run both paths against live side effects.

The IBM MCP Context Forge migration issue is a useful implementation signal because it treats capability propagation, input_required forwarding, retries, metrics, and deprecation as one gateway change rather than an isolated handler update. Use the same cross-layer scope for your rollout.

Watch for common migration failures

A compatibility adapter that silently falls back to legacy behavior can hide unsupported modern clients. Emit a metric for selected path, protocol version, client identity, round count, terminal status, and fallback reason. Alert on legacy usage that does not decline after rollout.

Treat requestState as untrusted even though your server created it. The client echoes it through an untrusted channel. Verify integrity, identity, method binding, parameter digest, expiry, release version, and single-use requirements on every retry.

Charge nested model work to the operation budget. Count rounds before dispatch, reserve cost before a provider call, and reject another round after cancellation or deadline expiry.

Preserve message history when translating between callback and MRTR shapes. Keep tool-call and tool-result pairs in provider-valid order. Add a fixture that requires two tool-mediated rounds so a one-round happy path cannot conceal the defect.

Retain the legacy handler after code search reaches zero because production clients may still depend on it. Removal requires observed zero legacy selections for a defined window, no supported-client exception, passing negative tests, and a rollback plan.

Use a hard removal gate

Remove pushed MCP Sampling only when all of these statements are true:

  • every known call site has a selected target path;
  • modern clients pass MRTR or direct-provider tests;
  • supported legacy clients have upgraded or an explicit end-of-support decision exists;
  • operation, round, deadline, cancellation, and side-effect identities survive every retry;
  • duplicate retries return the existing result rather than running work again;
  • malformed or tampered state fails closed;
  • multi-round tool history is preserved;
  • telemetry shows no unexplained fallback or legacy traffic during the observation window;
  • rollback restores the adapter without changing product state semantics.

Start by exporting the Sampling inventory and adding the four-path compatibility matrix to CI. Do not switch production traffic until the matrix proves cancellation, repeated retries, multi-round tool history, and side-effect receipts across both protocol eras.

Be first in line.

Join the waitlist and we'll email you the moment it's ready. No sales call.

Try the demo →
or talk to us