Skip to content

MCP now: understand the request before choosing an SDK

Checked: 2026-10-18. Read first: this update, then the numbered lectures for concepts and explicitly dated compatibility examples. Time: 30–45 minutes. Artifact: a version-labelled request/result transcript and a failure analysis. No paid API or robot hardware is needed for the paper exercise.

The official versioning page identifies 2026-07-28 as current. The older 2025-11-25 initialization examples remain useful for existing clients, but changing a date string does not migrate their wire contract. An SDK package version and a protocol revision are different identifiers; verify both endpoints' supported revisions.

1. The two contracts

Question 2025-11-25 compatibility examples Current 2026-07-28 contract
How is the version established? initialize, then notifications/initialized Version and client capabilities accompany every request
Must the client discover first? Initialization begins the session Server implements server/discover; client may use it before another operation
Does a connection identify a conversation? Some examples rely on protocol sessions No; cross-call application state uses explicit handles
What marks a completed result? result without a discriminator resultType: "complete"
How does additional input flow? Server-initiated reverse requests An input_required result followed by a retry carrying input responses

The first two rows follow versioning and compatibility; the message/state distinctions follow the base protocol and multi round-trip pattern. A dual-era endpoint may serve both contracts. A current-only client does not automatically interoperate with an old-only server.

The current change log also removes protocol session headers and SSE replay, replaces old resource subscriptions with subscriptions/listen, adds cache metadata to cacheable results, and moves long-running Tasks into an extension. These are behavior changes that deserve tests, not a configuration-only upgrade.

2. Work one robot-status request by hand

Assume the server has already advertised a read-only robot_status tool accepting robot_id. This is a constructed transcript, not a claim of an executed SDK integration. The request body is:

{
  "jsonrpc": "2.0",
  "id": "status-17",
  "method": "tools/call",
  "params": {
    "name": "robot_status",
    "arguments": {"robot_id": "sim-01"},
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {},
      "io.modelcontextprotocol/clientInfo": {
        "name": "course-transcript-reader",
        "version": "1.0"
      }
    }
  }
}

A successful teaching response is:

{
  "jsonrpc": "2.0",
  "id": "status-17",
  "result": {
    "resultType": "complete",
    "content": [{"type": "text", "text": "sim-01 is idle"}],
    "isError": false,
    "_meta": {
      "io.modelcontextprotocol/serverInfo": {
        "name": "course-status-server",
        "version": "1.0"
      }
    }
  }
}

Compare the ID, method, argument schema, metadata, and result type with the tool specification. This body alone is not a complete HTTP exchange: the transport has its own required headers and authorization contract. A tool description or self-reported client name does not authenticate a caller.

Guided variation A: remove io.modelcontextprotocol/clientCapabilities. Answer: the current base protocol requires that field even when its value is {}; the request is malformed (-32602, and HTTP 400 on that transport).

Guided variation B: use an unsupported protocol version. Answer: distinguish UnsupportedProtocolVersion (-32022) from malformed parameters. Select a mutually supported revision or report incompatibility; do not silently interpret the same body using an unrelated older contract.

Guided variation C: the client loses the reply and sends a new request ID. Did the operation happen once? Answer: the transport cannot establish that. Reading status again is different from repeating a state-changing operation. A mutating service needs application-level deduplication or an explicit outcome query; a new JSON-RPC ID is not an idempotency key.

3. Learn the current feature boundaries

Tools, resources, prompts, and elicitation remain the useful starting concepts. Roots, Sampling, and Logging are deprecated, not yet removed; the deprecated-feature registry defines their status. Treat Lecture 04's reverse-primitives examples and Lecture 05's related Context methods as compatibility study. Do not add new dependencies on those features merely because an old SDK exposes them.

MCP Apps, Tasks, and other extensions need explicit support from both sides. The base protocol being stateless does not erase application state, authorization, or long-running work. For robotics, a supervisory status/task interface is separate from a real-time control loop and must keep its existing action bounds and watchdog behavior.

4. Independent compatibility exercise

Make a table for old-only, current-only, and dual-era clients against the same three server types. Predict every pairing before consulting the official compatibility table. Explain one failure without treating it as an authentication error.

Then pick an installed SDK version, record its lock and supported protocol date, and capture one actual read-only request/result. Label it executed only after running it; the transcript above is merely source-checked. Add one unsupported-version case and one malformed request, preserving error bodies. If your installed SDK only supports the older revision, show that explicitly instead of relabelling its traffic as current.

Pass: explain why connection identity is not conversation identity, why retry is not exactly-once execution, and why changing an SDK cannot by itself update a peer. Retain one successful transcript and two actual failures for the implementation portion. The shared rubric applies; reading the examples alone does not complete the server-building capstone.