Stateless MCP Migration: How to Regression Test Your Server

What Does Stateless MCP Mean?

Stateless MCP means every request stands on its own. In the 2026-07-28 revision, each request carries its protocol version and client capabilities in _meta, the initialize handshake is gone, and servers MUST implement server/discover to advertise their supported versions, capabilities and identity, according to the 2026-07-28 changelog.

The discover result can also carry an optional instructions field, which the spec describes as natural-language guidance for LLMs on how to use the server. That text is written for the model, so give it a security review of its own, separate from this migration.

Capture a Baseline on the Legacy Spec

Record what your server does today before any dependency moves, because a v2 SDK can change the legacy wire shape too: a TypeScript v2 server advertises differently shaped inputSchema entries in tools/list, the Python v2 client adds a _meta envelope to every outbound request, and a Python v2 server answers unknown methods and missing resources with new error codes. Run every capture with the MCP Inspector pinned to the legacy era, so the snapshot matches what 2025-11-25 clients see.

Give the same server one entry per era in a config file. The catalog format in the Inspector configuration docs takes a protocolEra field on each server, and it defaults to legacy.

{
  "mcpServers": {
    "orders-legacy": {
      "command": "node",
      "args": ["build/index.js"],
      "protocolEra": "legacy"
    },
    "orders-auto": {
      "command": "node",
      "args": ["build/index.js"],
      "protocolEra": "auto"
    },
    "orders-modern": {
      "command": "node",
      "args": ["build/index.js"],
      "protocolEra": "modern"
    }
  }
}

Capture these on the legacy entry before you change anything:

• tools/list - the full list, with every inputSchema and outputSchema.
• Golden tool calls - one passing and one failing tools/call per tool, saved exactly as returned.
• Error envelopes - an unknown tool, invalid arguments and a missing resource, with the JSON-RPC code each one returns.
• Resources and prompts - resources/list, resources/read and prompts/list, if your server offers them.
• Stateful flows - any sequence where one call depends on an earlier one, since that is where session removal bites.

The MCP Inspector CLI reference documents every flag below. With --format json it writes a single JSON object to stdout with no banners, so each capture is a file you can diff.

set -euo pipefail
mkdir -p baseline

npx @modelcontextprotocol/inspector@2.8.0 --cli --config ./mcp.json --server orders-legacy \
  --method tools/list --format json > baseline/tools-list.legacy.json

# One golden call per tool; get_order and its argument stand in for your own tools
npx @modelcontextprotocol/inspector@2.8.0 --cli --config ./mcp.json --server orders-legacy \
  --method tools/call --tool-name get_order --tool-args-json '{"order_id":"A-1001"}' \
  --format json > baseline/get_order.legacy.json

Failing calls need their own handling. The MCP Inspector CLI reference maps each outcome to an Inspector exit code:

• Exit 0 - success.
• Exit 1 - a usage or unexpected error.
• Exit 3 - the server requires authentication.
• Exit 4 - the server is unreachable.
• Exit 5 - a tool error, so a tools/call that returns isError: true still prints its payload while the Inspector CLI exits 5.

Every non-zero exit also writes one JSON line to stderr, so end these calls with || true and keep both streams:

# A failing call; the order ID stands in for one your server rejects
npx @modelcontextprotocol/inspector@2.8.0 --cli --config ./mcp.json --server orders-legacy \
  --method tools/call --tool-name get_order --tool-args-json '{"order_id":"does-not-exist"}' \
  --format json > baseline/get_order.fail.legacy.json 2> baseline/get_order.fail.legacy.err.json || true

# orders://missing stands in for a URI your server does not have
npx @modelcontextprotocol/inspector@2.8.0 --cli --config ./mcp.json --server orders-legacy \
  --method resources/read --uri orders://missing --format json \
  > baseline/missing-resource.legacy.json 2> baseline/missing-resource.legacy.err.json || true

The stderr line names the CLI's own failure class and carries the server's message, but not the JSON-RPC error code. Assert the codes in a test that uses your SDK client, where the TypeScript client's ProtocolError exposes the number as code, and diff the stderr files as they are.

Then freeze the conformance result at the legacy revision. The MCP conformance README describes --requirements as running exactly what a spec revision requires, frozen at its release, and lists 2025-11-25 and 2026-07-28. Its server examples target a URL, so run it against the Streamable HTTP build of your server.

npx @modelcontextprotocol/conformance@0.2.0-alpha.11 server \
  --url http://localhost:3000/mcp --requirements 2025-11-25 \
  --expected-failures ./conformance-baseline-2025.yml

List the scenarios that fail on your server today in the baseline file, in the format the README shows. The two entries below are the README's own examples, so replace them, because a listed scenario that passes makes the run exit 1:

server:
  - tools-call-with-progress
  - resources-subscribe

Keep the baseline trustworthy:

• Verbatim arguments - use --tool-args-json for golden calls. It passes the argument object verbatim, while --tool-arg coerces each value by JSON-parsing it, so "012" becomes the number 12 and the baseline records a call you never meant to make.
• Conformance version - on September 29, 2026, the npm latest tag pointed to 0.1.16, whose README has no --requirements flag, while the alpha tag pointed to 0.2.0-alpha.11, which has it. Pin the version you ran.
• Inspector version - the commands in this guide pin MCP Inspector 2.8.0, the npm latest tag on September 29, 2026, so a later release cannot change the capture format under you. Recapture the baseline whenever you move a pin.
• Storage - commit the baseline folder and the conformance baseline file next to the server code, so every later run diffs against the same pre-migration capture.

Upgrade the SDK Before the Protocol

Change one variable at a time. The maintainers of the official reference servers track their own migration in issue #4857 of the modelcontextprotocol/servers repository on GitHub, Tracker: 2026-07-28 Spec Refactor, opened on September 26, 2026, and they order the work in waves.

• Wave 1 - "Tests come first so we can prove the supposedly transparent SDK migrations really are transparent." For your server, that is the legacy baseline from the previous section.
• Wave 2 - "No wire behavior changes; the Wave 1 suites must pass with only import and type changes." Bump the SDK, keep serving 2025-11-25, and rerun the baseline.
• Wave 3 - "Serve 2026-07-28 and legacy clients from the same server, and extend the test suites to cover the new spec." Opt in to the new revision and build the two-era matrix.

Neither SDK bump leaves the wire untouched. TypeScript v2 keeps the 2025-era protocol until you opt in, but it reshapes the tool schemas you advertise, and a Python v2 server picks up the new revision on upgrade. Both SDKs also have client-side catches:

• TypeScript default - the TypeScript SDK 2026-07-28 support guide states that "Nothing in v2 puts a 2026-07-28 byte on the wire by default", so a hand-constructed Client, Server or McpServer keeps speaking the 2025-era protocol until you opt in.
• TypeScript schemas - the TypeScript upgrade-to-v2 guide warns that "Your advertised tool schemas change shape on the wire": the same registerTool calls produce tools/list inputSchema entries that differ from v1 (JSON Schema 2020-12 idioms, different additionalProperties handling, no execution.taskSupport member), so re-baseline golden tools/list snapshots after the bump.
• Python server - the Python SDK's Serving legacy clients page says "Both eras are always on", with no option to reject or disable an era, so a v2 server answers 2026-07-28 requests alongside initialize from the moment you bump. For a Python server, run the modern matrix cells in wave 2, not wave 3.
• Python default - the Python SDK v2 migration guide says the v2 Client defaults to mode='auto', which probes server/discover and lands on 2026-07-28 against a v2 server. A v1 test that drove ctx.elicit(), create_message() or list_roots() through the in-process client now fails with NoBackChannelError, even with the callbacks set.
• Python renames and codes - FastMCP becomes MCPServer, unknown request methods now return -32601 instead of -32602, and a missing resource returns -32602 where v1 returned code 0 with no data, so some error assertions change in wave 2 with no protocol opt-in at all.
• Python wire shape - mode="legacy" reproduces the initialize handshake, but the guide notes that the per-request wire shape still differs from v1, because every outbound request now carries a _meta envelope.

The Python guide shows both forms of the v2 client. Pin the legacy era in the tests you carry through wave 2:

from mcp.client import Client

# v2 default: mode='auto' negotiates 2026-07-28 against a v2 server,
# where server-initiated requests raise NoBackChannelError
async with Client(server) as client:
    result = await client.call_tool("my_tool", {"x": 1})

# A v1-style test that drives sampling, elicitation or roots stays on the legacy era
async with Client(server, mode="legacy", sampling_callback=..., elicitation_callback=..., list_roots_callback=...) as client:
    ...

• Wave 2 tests - keep mode="legacy" on every existing test until the SDK bump is merged, so the suite still exercises the path your current clients use.
• Wave 3 tests - add new tests with mode='2026-07-28'; the guide says that value pins a version without probing.
• Accepted diffs - after the bump, rerun the baseline and accept only the diffs you can trace to the SDK migration guides, such as the TypeScript inputSchema reshaping and the Python unknown-method and missing-resource codes.

Build a Two-Era Test Matrix

Wave 3 opts a TypeScript server in; a Python v2 server is already dual-era. The TypeScript guide shows createMcpHandler as the HTTP entry point, and its default legacy: 'stateless' option serves 2026-07-28 and 2025 clients per request. For stdio, serveStdio also serves 2025 clients unless you pass legacy: 'reject'.

import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';

// Default legacy: 'stateless' serves 2026-07-28 and 2025 clients per request
const handler = createMcpHandler(() => {
  const server = new McpServer(
    { name: 'my-server', version: '1.0.0' },
    { capabilities: { tools: {} } }
  );
  return server;
});

Then run every scenario once per era. The spec page on versioning and compatibility gives the expected outcome for each client and server pairing, and these are the cells a migrating server needs:

Run the matrix with these rules:

• Set the era explicitly - the Inspector's legacy default is deliberate, because its docs say a debugging tool must not auto-probe. A matrix that never sets protocolEra runs one cell and reports green.
• Budget for the probe - the Inspector docs warn that a server/discover probe stalls against silent legacy stdio servers, and the stdio transport spec treats no answer within a reasonable timeout as a legacy server, so the auto cell against the pre-migration build should pass once the client falls back to initialize. The CLI's --connect-timeout, in milliseconds, bounds that whole connection attempt, so set it longer than the probe timeout; a connect timeout on that cell means the fallback never finished.
• Assert the era - read back which era was negotiated once the connection opens. The TypeScript client reports it through getProtocolEra().
• Expect loud failures - a TypeScript client pinned to 2026-07-28 rejects with SdkError(EraNegotiationFailed) against your pre-migration build (the guide's 2025-only server), which is the failure the last cell expects.
• Test in process - the TypeScript guide points a StreamableHTTPClientTransport at handler.fetch, so the 2026 path runs without opening a socket.
• Legacy push features - the TypeScript guide says createMcpHandler's default legacy: 'stateless' builds a fresh instance per request with no return path for server-to-client requests, so a tool rewritten in the inputRequired form that needs elicitation, sampling or roots from a 2025 HTTP client gets a clean capability refusal, returned as an isError result. A sessionful v1 server keeps those requests working by routing legacy traffic with isLegacyRequest() to its existing handler in front of a legacy: 'reject' entry, so add a legacy-client elicitation test to the matrix.
• Conformance at both revisions - the README says "Scenarios run at their revision's wire version", so --requirements 2025-11-25 exercises the initialize path and --requirements 2026-07-28 the stateless one, against the same build.

The TypeScript guide pins a modern client this way:

// Matrix cell: modern client, no fallback
const client = new Client(
  { name: 'my-client', version: '1.0.0' },
  { versionNegotiation: { mode: { pin: '2026-07-28' } } }
);
await client.connect(transport);
client.getProtocolEra(); // returns 'modern' | 'legacy'

Test Each Removed and Deprecated Feature

The baseline proves that what stayed still works, but nothing in it calls the replacement paths. Every removal in the changelog needs a named test of its own.

Add Authorization Regression Checks

The authorization changes land mostly on clients and authorization servers, so they matter if your team ships either one alongside the MCP server. MCP security explains why MCP authorization is harder to get right than API authorization.

• Issuer check - authorization servers SHOULD include iss in the authorization response per RFC 9207, which exists to defend against mix-up attacks, and clients MUST validate a present iss against the recorded issuer before redeeming the code. Send a response with the wrong iss and expect the client to stop before redemption.
• application_type - clients must specify an appropriate application_type during Dynamic Client Registration. Capture the registration request and assert the field is present.
• Issuer-keyed credentials - clients MUST key stored credentials by issuer, MUST NOT reuse them with a different authorization server, and MUST re-register when the server changes. Point the client at a second authorization server and assert a fresh registration.
• CIMD and DCR - Dynamic Client Registration is deprecated in favor of Client ID Metadata Documents but stays available for authorization servers that do not support them, so test both paths. The MCP Inspector CLI takes a --client-metadata-url flag for the CIMD path.

Diff Stateless MCP Output Against the Baseline

A raw diff of 2026-07-28 output against the legacy baseline goes red on fields that were never regressions. Normalize the era-specific ones first; generic schema drift checks, such as a parameter entering the required array, are covered in MCP testing.

This Node script applies the first four rows to a successful MCP Inspector CLI snapshot and sorts keys, so the only lines left in a diff are real changes:

// normalize.mjs: strip era-only fields from an MCP Inspector CLI --format json snapshot
import { readFileSync } from "node:fs";

const SERVER_INFO = "io.modelcontextprotocol/serverInfo";
const sortKeys = (v) =>
  Array.isArray(v) ? v.map(sortKeys)
  : v && typeof v === "object"
    ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sortKeys(v[k])]))
    : v;

const snapshot = JSON.parse(readFileSync(process.argv[2], "utf8"));
if (!snapshot.result) throw new Error(process.argv[2] + " holds no result; diff error snapshots as they are");
const result = { ...snapshot.result };

delete result.ttlMs;       // 2026-07-28 cache hints, absent from legacy results
delete result.cacheScope;
if (result._meta) {
  const { [SERVER_INFO]: _selfReported, ...rest } = result._meta;
  if (Object.keys(rest).length) result._meta = rest;
  else delete result._meta;
}
result.resultType ??= "complete";   // legacy results omit it
if (Array.isArray(result.tools)) {
  result.tools = [...result.tools].sort((a, b) => a.name.localeCompare(b.name));
}

process.stdout.write(JSON.stringify(sortKeys(result), null, 2) + "\n");

Schema diffs still need a human. The changelog loosens inputSchema and outputSchema to allow any JSON Schema 2020-12 keywords, and structuredContent to allow any JSON value, so a schema that gains a $ref can be a legitimate change. TestMu AI's JSON compare tool shows two normalized files side by side when you need to read a diff before accepting it.

Gate CI on the conformance run as well as the diff:

• Stale entries fail too - with --expected-failures, the conformance runner exits 1 on an unexpected regression and also on a stale entry, a baselined scenario that now passes, so the file shrinks as you fix things.
• One file per revision - keep conformance-baseline-2025.yml and conformance-baseline-2026.yml apart, because a scenario can fail on one wire and pass on the other.

set -euo pipefail

# --stored-auth-only fails fast with auth_required instead of waiting on a browser callback
npx @modelcontextprotocol/inspector@2.8.0 --cli --config ./mcp.json --server orders-modern \
  --stored-auth-only --method tools/list --format json > tools-list.modern.json

node normalize.mjs baseline/tools-list.legacy.json > legacy.norm.json
node normalize.mjs tools-list.modern.json > modern.norm.json
diff -u legacy.norm.json modern.norm.json

npx @modelcontextprotocol/conformance@0.2.0-alpha.11 server \
  --url http://localhost:3000/mcp --requirements 2026-07-28 \
  --expected-failures ./conformance-baseline-2026.yml

Catch Agent Regressions After the MCP Migration With Agent Assurance

A server can pass every conformance scenario and still change what an agent does, because a reordered tool list, a reworded description or a new schema keyword all reach the model on its next call.

Agent Assurance, which you run as Rook CLI, checks what the run changed: it invokes the agent that calls your server for real, so point it at staging. If the confirmation tool from the opening errors, the agent may still say the action went through; that claim never counts as proof.

For its own discovery and verifier calls, Rook CLI 0.1.5 connects only to stdio MCP servers and lists HTTP, SSE and WebSocket definitions as unsupported-transport, so reaching a Streamable HTTP build that way needs a stdio bridge; see how to configure MCP servers in Agent Assurance. The Agent Assurance docs do not name the MCP revision Rook CLI speaks, so keep the server dual-era for these runs.

Rook CLI /help mcp: a help screen from a saved demo project, Rook CLI 0.1.5

For the calls your agent sends through the migrated server, Agent Assurance checks:

• Calls to the migrated server - each call the agent makes to your server is held against the agent's declared tool surface, provided the profile's hooks return the calls they saw; otherwise those criteria cannot be decided and come back Unable to Verify.
• Real tool lists - discovery asks each approved stdio server what tools it really has rather than trusting the config, and a project or discovered definition whose command, arguments or environment references change goes back to pending approval.
• No unexpected writes - an order lookup scenario can assert that a write tool was not_called, which again depends on hooks that report observed calls.
• Read-only verifiers - a scenario can require an MCP verifier such as get_order, which judges use under instructions to leave the order untouched; if that verifier's server cannot be called, the skip reason names it.

Compared with a typical eval tool's defaults:

Read the eval column as that category's usual setup, not any one product: several eval tools score tool calls, and a custom scorer can check what a write changed.

To run it against the migrated agent, install Rook CLI from npm:

npm install -g @testmuai/rook
rook --version

It needs Node 22 or newer. Start rook from the codebase of the agent that calls your server; for other install routes, see the Rook CLI install guide.

To drive it from Claude Code, set up the rook skill:

npx @testmuai/rook-skill@latest install --agent claude-code

Then, in Claude Code, ask for a bounded run:

/rook Use the staging profile for the agent that calls our orders MCP server. Show the MCP servers it declares and their approval state, then propose three scenarios for the 2026-07-28 migration: an order lookup that must not call a write tool, an action that needs the user's confirmation, and a missing order. List every write those scenarios could make through the server, and do not generate them or invoke the agent until I approve.

Note: Each Agent Assurance run snapshots the agent definition, profile and scenarios it used, so rerunning the same scenarios after the migration lets the report tell a regression from a change to those definitions.

Conclusion

Record the legacy baseline this week, while your server still speaks only 2025-11-25: tools/list, golden calls and error envelopes captured with protocolEra set to legacy, plus a conformance run at that revision.

Then bump the SDK (TypeScript keeps the 2025 protocol but reshapes the tool schemas you advertise, while a Python v2 server starts answering 2026-07-28 too), opt in behind a dual-era handler, and run the two-era matrix before any client pins 2026-07-28. Add the named tests for sessions, logging, MRTR and subscriptions, and diff against the normalized baseline in CI.

Finish a stateless MCP migration at the agent layer, where Agent Assurance grades each criterion against the evidence a run leaves, such as files changed and tool calls made. Put the deprecated paths on a calendar too, since Roots, Sampling and Logging become eligible for removal with the first revision released on or after 2027-07-28.