Get Started

MCP Model Input: Sampling Migration and Stateless MRTR

MCP 2026-07-28 deprecates Sampling for new designs and removes the server-to-client request channel. If an existing workflow still needs the client's model, the server returns an input_required result and the client retries the original request with the model output. The reasoning loop becomes explicit, bounded, and stateless at the protocol layer.

75 minutesBuildPythonFree lesson

Learning Objectives

  • Explain why Sampling is deprecated in MCP 2026-07-28 and choose the direct model integration default for new servers.
  • Implement a compatibility workflow that carries sampling/createMessage through Multi Round-Trip Requests (MRTR).
  • Put the protocol revision and client capabilities in every request _meta object.
  • Return resultType: "input_required" and retry the original method with a fresh JSON-RPC id.
  • Integrity-protect requestState and bind it to the principal, method, arguments, and expiry.
  • Bound model-assisted loops with capability checks, approval, response validation, and a round limit.

The Decision Before the Protocol

A tool such as summarize_repo needs two kinds of work:

  1. Deterministic work: list files, read allowed files, validate paths, and assemble content.
  2. Model work: choose representative files and synthesize the summary.

You now have two valid architectures.

New server: integrate with a model provider directly

This is the current default. The server owns model selection, credentials, budgets, retries, and observability. It returns one ordinary tools/call result to the MCP client.

Choose this when the server is already a hosted service or when predictable model behavior matters more than using the host's model.

Existing Sampling workflow: migrate it to MRTR

Sampling still exists during its deprecation window. A server targeting 2026-07-28 cannot send a live sampling/createMessage request back to the client. It instead embeds that request in an InputRequiredResult.

Choose this compatibility path only when using the client's model and credentials is a real product requirement. Record a removal plan because new implementations should not adopt deprecated Sampling.

The Stateless Contract

The July 2026 protocol has no initialize exchange, no notifications/initializedand no Mcp-Session-Id. Every request carries the information that used to live in the handshake:

JSON
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "summarize_repo",
    "arguments": {"audience": "developer"},
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {"sampling": {}},
      "io.modelcontextprotocol/clientInfo": {
        "name": "lesson-client",
        "version": "1.0.0"
      }
    }
  }
}

The server validates the revision on every request. A missing or non-string version is invalid params, -32602. An unsupported string returns -32022 with exact data {"supported":["2026-07-28"],"requested":"<client version>"}. A missing Sampling capability returns -32021 with data.requiredCapabilities set to {"sampling":{}}.

An envelope without a JSON-RPC id is a notification. The receiver may process it, but it emits neither a success response nor an error response. A Streamable HTTP adapter returns 202 Accepted with no body for an accepted notification.

The server also implements server/discover with the exact supportedVersions key, capabilities, ttlMsand cacheScope so a client can learn and cache the server contract before calling a tool. Because discovery advertises toolsthe server also implements mandatory tools/list. Its deterministic summarize_repo descriptor includes a valid object inputSchemaresultType: "complete"server identity metadata, and public cache hints.

Every successful modern result has a discriminator:

  • resultType: "complete" means the operation finished.
  • resultType: "input_required" means the client must fulfill embedded requests and retry.
  • Extensions may define additional result types. The Tasks extension adds "task" in Lesson 13.

One MRTR Round

The server cannot call the client while handling the request. It returns this result instead:

JSON
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resultType": "input_required",
    "inputRequests": {
      "pick_files": {
        "method": "sampling/createMessage",
        "params": {
          "messages": [
            {
              "role": "user",
              "content": {
                "type": "text",
                "text": "Choose three representative files and return a JSON array."
              }
            }
          ],
          "systemPrompt": "Return only the requested value.",
          "modelPreferences": {
            "costPriority": 0.8,
            "intelligencePriority": 0.2
          },
          "maxTokens": 400
        }
      }
    },
    "requestState": "opaque-integrity-protected-value"
  }
}

The client verifies that it supports Sampling, applies its approval and model policies, and obtains a model response. Then it sends a new request with a different JSON-RPC id:

JSON
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "summarize_repo",
    "arguments": {"audience": "developer"},
    "inputResponses": {
      "pick_files": {
        "role": "assistant",
        "content": {
          "type": "text",
          "text": "[\"README.md\", \"server.py\", \"docs/intro.md\"]"
        },
        "model": "host-model",
        "stopReason": "endTurn"
      }
    },
    "requestState": "opaque-integrity-protected-value",
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {"sampling": {}}
    }
  }
}

The retry is not a continuation of a protocol session. It is a new request that repeats the original method and arguments, adds only the current round's inputResponsesand echoes requestState byte for byte.

MRTR is allowed only on tools/callprompts/getand resources/read. A server must not return input_required from unrelated methods.

Multi-Round State

This lesson needs two model calls:

  1. pick_files returns a JSON array.
  2. summary returns the final prose.

Each retry carries only the responses for that round. The server therefore puts the phase and validated intermediate data into the next requestState.

Treat that value as attacker-controlled. Signing a raw phase name is not enough. Bind the state to:

  • the authenticated principal, not self-reported clientInfo;
  • the originating method;
  • a digest of the original arguments;
  • a short expiry;
  • the current phase and validated intermediate values.

Use HMAC when confidentiality is not required. Use authenticated encryption when the client must not read the state. Reject a bad signature, expired value, changed principal, or changed arguments with -32602.

The client must not parse or modify requestState. Its only job is to echo the exact string on the retry.

Model Preferences Are Hints

costPriorityspeedPriorityand intelligencePriority are independent preferences. They are not a probability distribution and do not need to sum to one. The client may ignore them because the client owns model policy.

Keep includeContext at "none" if you maintain a legacy Sampling flow. Other context modes increase leakage risk and are themselves deprecated. Pass the minimum explicit context in the request.

Safety Invariants

The client is the trust boundary for embedded Sampling requests.

  • Show the user what the server is asking the model to do when policy requires approval.
  • Cap MRTR rounds. A malicious server can otherwise create a model-spend loop.
  • Validate every sampling response before using it as a filename, URL, or tool input.
  • Limit bytes and tokens per round.
  • Refuse an input request that was not declared in current client capabilities.
  • Keep model output out of authorization decisions.
  • Log the originating method and input-request key without logging sensitive prompt content.

clientInfo and serverInfo are display and diagnostics metadata. Never use either as an authenticated identity.

Build It

code/main.py implements the full two-round flow with no third-party package:

  • server/discover returns supportedVersionsadvertises tool support, and returns cache hints.
  • tools/list returns a deterministic, cacheable summarize_repo descriptor with an object input schema.
  • tools/call validates per-request metadata.
  • The first result embeds sampling/createMessage for file selection.
  • The first retry validates the model result and embeds a second request.
  • HMAC-protected requestState carries the phase between independent requests.
  • The final result uses resultType: "complete".

The fake host model makes the example deterministic. Replace only fake_host_model when connecting a real host. The server-side state machine should stay deterministic and testable.

Use It

From the repository root:

Terminal
cd phases/13-tools-and-protocols/11-mcp-sampling/code
python3 main.py
python3 -m unittest discover tests -v

Expected checkpoints:

  • Discovery returns a complete result with ttlMs and cacheScope.
  • Tool discovery returns the same sorted descriptor with resultTypeserver identity, and cache hints.
  • Missing capabilities and unsupported versions use exact -32021 and -32022 error data.
  • An id-less notification produces no JSON-RPC response.
  • Request ids are [1, 2, 3]proving each MRTR round is independent.
  • The first two results are input_required.
  • The final result is complete and contains the selected files plus summary.
  • Changing the original arguments on a retry fails the request-state check.

Ship It

outputs/skill-sampling-loop-designer.md is now a migration planner. It first decides whether Sampling should be removed in favor of direct model integration. If compatibility is required, it produces the MRTR rounds, state binding, capability gate, budget, validation, and removal plan.

Exercises

  1. Change the file-selection response to invalid JSON. Confirm the server returns -32602 instead of trusting model output.
  2. Change audience between the first call and retry. Explain why the sealed state blocks cross-request reuse.
  3. Add a third round that asks the host to critique the summary. Carry the earlier summary inside signed state and cap the entire flow at three rounds.
  4. Remove Sampling by replacing the fake host callback with a server-owned model adapter. List which approval, billing, and observability responsibilities move to the server.
  5. Add an expiry test using a state value that is one second past its deadline.

Key Terms

TermMeaning in 2026-07-28
SamplingDeprecated feature that asks the client's model for a completion
MRTRStateless retry pattern for client input required during a request
InputRequiredResultResult with resultType: "input_required"
inputRequestsServer-assigned map of embedded elicitation, sampling, or roots requests
inputResponsesCurrent round's client results keyed like inputRequests
requestStateOpaque server state echoed exactly by the client and verified by the server
resultTypeRequired discriminator for modern MCP results
Direct model integrationRecommended replacement for new servers that need model inference
Capability gateRule that prevents sending an embedded request the client did not advertise
Loop budgetMaximum rounds, tokens, bytes, time, and spend allowed for the operation

Legacy Compatibility

A client pinned to 2025-11-25 may still use the older server-initiated sampling/createMessage flow over a live connection. Keep that behavior in a version-specific adapter only. Do not make the sessionful path the architecture for a 2026-07-28 server.

Official SDKs can translate modern input_required handlers for older peers. That shim is a compatibility boundary, not permission to add new session-dependent logic.

Further Reading

Check what you learned

6 questions. Answer each one to see why.

Question 1 of 60 correct

A new MCP server needs model inference. What is the default architecture under 2026-07-28?

The full code

Every file for this lesson. Copy it, run it, then change it.

main.py
"""Phase 13 Lesson 11: model input through stateless MCP MRTR.

Lesson: ../docs/en.md
Specification: https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr
This example uses only Python's standard library.
Run: python3 main.py
"""

from __future__ import annotations

import base64
import hashlib
import hmac
import json
import time
from copy import deepcopy
from dataclasses import dataclass
from typing import Any


PROTOCOL_VERSION = "2026-07-28"
PROTOCOL_META = "io.modelcontextprotocol/protocolVersion"
CAPABILITIES_META = "io.modelcontextprotocol/clientCapabilities"
CLIENT_INFO_META = "io.modelcontextprotocol/clientInfo"
SERVER_INFO_META = "io.modelcontextprotocol/serverInfo"
SERVER_SECRET = b"lesson-11-demo-secret-change-in-production"

FAKE_REPO = {
    "README.md": "A small notes server used to teach stateless MCP.",
    "server.py": "def dispatch(request): return handle(request)",
    "client.py": "def retry(request, inputs, state): ...",
    "LICENSE": "MIT",
    "tests/test_server.py": "def test_stateless_retry(): ...",
    "docs/intro.md": "The server has no protocol session state.",
}
TOOLS = [
    {
        "name": "summarize_repo",
        "description": "Select representative repository files and summarize them.",
        "inputSchema": {
            "type": "object",
            "properties": {
                "audience": {
                    "type": "string",
                    "description": "Audience for the final repository summary.",
                }
            },
            "required": [],
        },
    }
]


@dataclass
class McpError(Exception):
    code: int
    message: str
    data: dict[str, Any] | None = None


def request_meta(*, sampling: bool = True) -> dict[str, Any]:
    capabilities: dict[str, Any] = {"sampling": {}} if sampling else {}
    return {
        PROTOCOL_META: PROTOCOL_VERSION,
        CAPABILITIES_META: capabilities,
        CLIENT_INFO_META: {"name": "lesson-client", "version": "1.0.0"},
    }


def _server_meta() -> dict[str, Any]:
    return {SERVER_INFO_META: {"name": "mrtr-demo", "version": "1.0.0"}}


def complete(**fields: Any) -> dict[str, Any]:
    return {"resultType": "complete", **fields, "_meta": _server_meta()}


def validate_request_meta(params: dict[str, Any]) -> dict[str, Any]:
    meta = params.get("_meta")
    if not isinstance(meta, dict):
        raise McpError(-32602, "missing request _meta")
    requested_version = meta.get(PROTOCOL_META)
    if not isinstance(requested_version, str):
        raise McpError(-32602, "missing protocol version")
    if requested_version != PROTOCOL_VERSION:
        raise McpError(
            -32022,
            "unsupported protocol version",
            {"supported": [PROTOCOL_VERSION], "requested": requested_version},
        )
    capabilities = meta.get(CAPABILITIES_META)
    if not isinstance(capabilities, dict):
        raise McpError(-32602, "missing client capabilities")
    return meta


def server_discover(params: dict[str, Any]) -> dict[str, Any]:
    validate_request_meta(params)
    return complete(
        supportedVersions=[PROTOCOL_VERSION],
        capabilities={"tools": {}},
        ttlMs=300_000,
        cacheScope="public",
    )


def tools_list(params: dict[str, Any]) -> dict[str, Any]:
    validate_request_meta(params)
    return complete(
        tools=sorted(deepcopy(TOOLS), key=lambda tool: tool["name"]),
        ttlMs=60_000,
        cacheScope="public",
    )


def _b64(data: bytes) -> str:
    return base64.urlsafe_b64encode(data).decode("ascii").rstrip("=")


def _unb64(value: str) -> bytes:
    return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))


def _arguments_digest(arguments: dict[str, Any]) -> str:
    encoded = json.dumps(arguments, sort_keys=True, separators=(",", ":")).encode()
    return hashlib.sha256(encoded).hexdigest()


def seal_request_state(payload: dict[str, Any]) -> str:
    body = json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
    signature = hmac.new(SERVER_SECRET, body, hashlib.sha256).digest()
    return f"{_b64(body)}.{_b64(signature)}"


def verify_request_state(
    token: str,
    *,
    principal: str,
    arguments: dict[str, Any],
    now: int | None = None,
) -> dict[str, Any]:
    try:
        body_part, signature_part = token.split(".", 1)
        body = _unb64(body_part)
        supplied = _unb64(signature_part)
    except (ValueError, TypeError) as exc:
        raise McpError(-32602, "invalid requestState encoding") from exc
    expected = hmac.new(SERVER_SECRET, body, hashlib.sha256).digest()
    if not hmac.compare_digest(supplied, expected):
        raise McpError(-32602, "requestState integrity check failed")
    try:
        state = json.loads(body)
    except json.JSONDecodeError as exc:
        raise McpError(-32602, "invalid requestState payload") from exc
    if state.get("principal") != principal:
        raise McpError(-32602, "requestState principal mismatch")
    if state.get("method") != "tools/call":
        raise McpError(-32602, "requestState method mismatch")
    if state.get("argumentsDigest") != _arguments_digest(arguments):
        raise McpError(-32602, "requestState arguments mismatch")
    if int(state.get("expiresAt", 0)) < (int(time.time()) if now is None else now):
        raise McpError(-32602, "requestState expired")
    return state


def _sampling_request(prompt: str, *, intelligence: float) -> dict[str, Any]:
    return {
        "method": "sampling/createMessage",
        "params": {
            "messages": [
                {"role": "user", "content": {"type": "text", "text": prompt}}
            ],
            "systemPrompt": "Return only the requested value.",
            "modelPreferences": {
                "costPriority": round(1.0 - intelligence, 2),
                "intelligencePriority": intelligence,
            },
            "maxTokens": 400,
        },
    }


def _input_required(
    key: str,
    prompt: str,
    state: dict[str, Any],
    *,
    intelligence: float,
) -> dict[str, Any]:
    return {
        "resultType": "input_required",
        "inputRequests": {key: _sampling_request(prompt, intelligence=intelligence)},
        "requestState": seal_request_state(state),
        "_meta": _server_meta(),
    }


def _sampling_text(input_responses: Any, key: str) -> str:
    if not isinstance(input_responses, dict):
        raise McpError(-32602, "inputResponses must be an object")
    response = input_responses.get(key)
    if not isinstance(response, dict):
        raise McpError(-32602, f"missing input response: {key}")
    content = response.get("content")
    if not isinstance(content, dict) or content.get("type") != "text":
        raise McpError(-32602, f"invalid sampling response: {key}")
    text = content.get("text")
    if not isinstance(text, str) or not text.strip():
        raise McpError(-32602, f"empty sampling response: {key}")
    return text


def tools_call(params: dict[str, Any], *, principal: str) -> dict[str, Any]:
    meta = validate_request_meta(params)
    if params.get("name") != "summarize_repo":
        raise McpError(-32602, "unknown tool")
    arguments = params.get("arguments", {})
    if not isinstance(arguments, dict):
        raise McpError(-32602, "arguments must be an object")
    capabilities = meta[CAPABILITIES_META]
    if "sampling" not in capabilities:
        raise McpError(
            -32021,
            "missing required client capability",
            {"requiredCapabilities": {"sampling": {}}},
        )

    state_token = params.get("requestState")
    if state_token is None:
        state = {
            "phase": "pick",
            "principal": principal,
            "method": "tools/call",
            "argumentsDigest": _arguments_digest(arguments),
            "expiresAt": int(time.time()) + 300,
        }
        prompt = (
            "Choose three representative files and return a JSON array. Files: "
            + json.dumps(sorted(FAKE_REPO))
        )
        return _input_required("pick_files", prompt, state, intelligence=0.2)

    if not isinstance(state_token, str):
        raise McpError(-32602, "requestState must be a string")
    state = verify_request_state(
        state_token,
        principal=principal,
        arguments=arguments,
    )
    responses = params.get("inputResponses")

    if state["phase"] == "pick":
        raw_picks = _sampling_text(responses, "pick_files")
        try:
            picks = json.loads(raw_picks)
        except json.JSONDecodeError as exc:
            raise McpError(-32602, "pick_files must return JSON") from exc
        if not isinstance(picks, list) or not all(isinstance(item, str) for item in picks):
            raise McpError(-32602, "pick_files must return a string array")
        picked = [name for name in picks if name in FAKE_REPO][:3]
        if not picked:
            raise McpError(-32602, "pick_files returned no known files")
        combined = "\n\n".join(f"{name}: {FAKE_REPO[name]}" for name in picked)
        next_state = {
            **state,
            "phase": "summarize",
            "picked": picked,
            "expiresAt": int(time.time()) + 300,
        }
        prompt = "Summarize these files in two sentences:\n\n" + combined
        return _input_required("summary", prompt, next_state, intelligence=0.8)

    if state["phase"] == "summarize":
        summary = _sampling_text(responses, "summary")
        return complete(
            content=[{"type": "text", "text": summary}],
            structuredContent={"picked": state["picked"], "summary": summary},
            isError=False,
        )

    raise McpError(-32602, "unknown requestState phase")


def dispatch(
    request: dict[str, Any],
    *,
    principal: str = "user-42",
) -> dict[str, Any] | None:
    is_notification = "id" not in request
    request_id = request.get("id")
    try:
        method = request.get("method")
        params = request.get("params", {})
        if not isinstance(params, dict):
            raise McpError(-32602, "params must be an object")
        if method == "server/discover":
            result = server_discover(params)
        elif method == "tools/list":
            result = tools_list(params)
        elif method == "tools/call":
            result = tools_call(params, principal=principal)
        else:
            raise McpError(-32601, "method not found")
        if is_notification:
            return None
        return {"jsonrpc": "2.0", "id": request_id, "result": result}
    except McpError as exc:
        if is_notification:
            return None
        error: dict[str, Any] = {"code": exc.code, "message": exc.message}
        if exc.data is not None:
            error["data"] = exc.data
        return {"jsonrpc": "2.0", "id": request_id, "error": error}


def fake_host_model(input_request: dict[str, Any]) -> dict[str, Any]:
    prompt = input_request["params"]["messages"][-1]["content"]["text"]
    if "Choose three" in prompt:
        text = json.dumps(["README.md", "server.py", "docs/intro.md"])
    else:
        text = (
            "This repository demonstrates a stateless MCP server and client retry loop. "
            "Each MRTR round carries all required state without a protocol session."
        )
    return {
        "role": "assistant",
        "content": {"type": "text", "text": text},
        "model": "host-model",
        "stopReason": "endTurn",
    }


def run_mrtr() -> tuple[dict[str, Any], list[int]]:
    base_params = {
        "name": "summarize_repo",
        "arguments": {"audience": "developer"},
        "_meta": request_meta(),
    }
    request_id = 1
    response = dispatch(
        {"jsonrpc": "2.0", "id": request_id, "method": "tools/call", "params": base_params}
    )
    seen_ids = [request_id]

    while response.get("result", {}).get("resultType") == "input_required":
        pending = response["result"]
        fulfilled = {
            key: fake_host_model(input_request)
            for key, input_request in pending["inputRequests"].items()
        }
        request_id += 1
        seen_ids.append(request_id)
        retry_params = {
            **base_params,
            "inputResponses": fulfilled,
            "requestState": pending["requestState"],
        }
        response = dispatch(
            {
                "jsonrpc": "2.0",
                "id": request_id,
                "method": "tools/call",
                "params": retry_params,
            }
        )
    return response, seen_ids


def main() -> None:
    discovery = dispatch(
        {
            "jsonrpc": "2.0",
            "id": 0,
            "method": "server/discover",
            "params": {"_meta": request_meta()},
        }
    )
    print("discover:", json.dumps(discovery["result"], indent=2))
    response, request_ids = run_mrtr()
    print("independent request ids:", request_ids)
    print("final:", json.dumps(response["result"], indent=2))


if __name__ == "__main__":
    main()