test(e2e): dual-era serving coverage — entry, stdio, sessionful BYO, streaming, and stamping scenarios

test/e2e/CLAUDE.md

@@ -58,6 +58,26 @@ note: 'stateless hosting has no server→client back-channel'
 `addedInSpecVersion` / `removedInSpecVersion` bound the spec versions a requirement applies to. A behavior changed by a spec release gets a sibling entry: the new entry lists every retired id it replaces in `supersedes` (an array, requires `addedInSpecVersion`), and each retired
 entry points back via `supersededBy` (requires `removedInSpecVersion`). A coverage gate enforces that the links resolve and are exactly symmetric.
 
+## The createMcpHandler entry arms (entryStateless / entryModern)
+
+Two transport arms host the dual-era HTTP entry (`createMcpHandler`) in process via an injected fetch, exactly like the other HTTP arms. They are era-fixed (`TRANSPORT_SPEC_VERSIONS`), so each registers cells on exactly one spec-version axis:
+
+- `entryStateless` — the entry with the `legacy: 'stateless'` slot; the scenario's plain client is served per request through the slot. Cells run on the 2025-11-25 axis only.
+- `entryModern` — the entry modern-only strict (no legacy slot); the scenario's client is put into pinned 2026-07-28 negotiation by the arm and the per-request `_meta` envelope is attached to every outgoing request/notification by the arm (a harness stop-gap until the client
+ emits it itself). Cells run on the 2026-07-28 axis only.
+
+Both arms are part of the default transport list, so unrestricted requirements run through the entry automatically. When a requirement cannot run on an entry arm, annotate it with a machine-readable reason instead of bending the test:
+
+```ts
+entryExclusions: [{ arm: 'entryModern', reason: 'method-not-in-modern-registry' /* optional note */ }];
+```
+
+Omitting `arm` excludes both arms. The reasons (`EntryExclusionReason` in types.ts) are the acceptance checklist for re-admitting cells when the corresponding entry feature lands; a coverage gate rejects annotations that would never have an effect. Requirement families that the
+per-request entry structurally cannot serve at all (server→client requests, sessions/resumability, standalone GET streams, subscriptions) are already expressed through their `transports` restrictions and need no annotation.
+
+Arm-specific helpers: `wire()`'s fourth argument also accepts `entry` (createMcpHandler hosting overrides — e.g. a `responseMode` or a bring-your-own `legacy` slot value), the returned `Wired.httpLog` records every HTTP exchange (request body, status, content-type, a readable
+response clone) for raw wire assertions, factories may accept the optional per-request context (`EntryServerFactory`), and `modernEnvelopeMeta()` builds the envelope for bodies that POST raw 2026-era requests through `wired.fetch`.
+
 ## Running
 
 From the repo root (the suite is the `@modelcontextprotocol/test-e2e` workspace package):

test/e2e/coverage.test.ts

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { expect, test } from 'vitest';
 
 import { REQUIREMENTS } from './requirements.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from './types.js';
 
 const E2E_DIR = path.dirname(fileURLToPath(import.meta.url));
 
@@ -88,6 +89,34 @@ test('every transport-restricted requirement explains why in note', () => {
  expect(missing).toEqual([]);
 });
 
+test('every entryExclusions annotation targets an entry arm the requirement would otherwise run on', () => {
+ const bad: string[] = [];
+ for (const [id, r] of Object.entries(REQUIREMENTS)) {
+ for (const exclusion of r.entryExclusions ?? []) {
+ const arms = exclusion.arm === undefined ? ENTRY_TRANSPORTS : [exclusion.arm];
+ for (const arm of arms) {
+ const transports = r.transports ?? ALL_TRANSPORTS;
+ if (!transports.includes(arm)) {
+ bad.push(`${id}: entryExclusions targets '${arm}', which the requirement's transports never include`);
+ continue;
+ }
+ const versions = ALL_SPEC_VERSIONS.filter(
+ v =>
+ (r.addedInSpecVersion === undefined || v >= r.addedInSpecVersion) &&
+ (r.removedInSpecVersion === undefined || v < r.removedInSpecVersion) &&
+ (TRANSPORT_SPEC_VERSIONS[arm]?.includes(v) ?? true)
+ );
+ if (versions.length === 0) {
+ bad.push(
+ `${id}: entryExclusions targets '${arm}', which registers no cells within the requirement's spec-version bounds`
+ );
+ }
+ }
+ }
+ }
+ expect(bad).toEqual([]);
+});
+
 test('supersedes/supersededBy links are symmetric and resolve', () => {
  const bad: string[] = [];
  for (const [id, req] of Object.entries(REQUIREMENTS)) {

test/e2e/fixtures/dual-era-stdio-server.ts

@@ -0,0 +1,29 @@
+/**
+ * Runnable dual-era stdio MCP server fixture for the dual-era stdio e2e cells.
+ *
+ * `eraSupport: 'dual-era'` is the single declared act on an otherwise ordinary
+ * hand-constructed McpServer connected to the unchanged StdioServerTransport.
+ * Spawned as a real child process (via tsx) by
+ * test/e2e/scenarios/stdio-dual-era.test.ts; exits when its stdin reaches EOF.
+ */
+
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { z } from 'zod/v4';
+
+const server = new McpServer(
+ { name: 'dual-era-stdio-e2e-fixture', version: '1.0.0' },
+ { capabilities: { tools: {} }, eraSupport: 'dual-era' }
+);
+
+server.registerTool(
+ 'echo',
+ {
+ description: 'Echoes the input text back as a text content block.',
+ inputSchema: z.object({ text: z.string() })
+ },
+ ({ text }) => ({ content: [{ type: 'text', text }] })
+);
+
+await server.connect(new StdioServerTransport());
+process.stderr.write('[dual-era-stdio-server] ready\n');

test/e2e/helpers/index.ts

@@ -15,30 +15,93 @@ import { PassThrough } from 'node:stream';
 
 import type { Client } from '@modelcontextprotocol/client';
 import { SSEClientTransport, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
-import type { EventStore, JSONRPCMessage, McpServer, Server } from '@modelcontextprotocol/server';
-import { InMemoryTransport, ReadBuffer, serializeMessage, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY } from '@modelcontextprotocol/core';
+import type {
+ CreateMcpHandlerOptions,
+ EventStore,
+ Implementation,
+ JSONRPCMessage,
+ McpRequestContext,
+ McpServer,
+ Server,
+ Transport as SdkTransport
+} from '@modelcontextprotocol/server';
+import {
+ createMcpHandler,
+ InMemoryTransport,
+ ReadBuffer,
+ serializeMessage,
+ WebStandardStreamableHTTPServerTransport
+} from '@modelcontextprotocol/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 
-import type { Transport } from '../types.js';
+import type { SpecVersion, Transport } from '../types.js';
 import { startLegacySseHost } from './sse-host.js';
 import type { SnifferOptions } from './wire-sniffer.js';
 import { sniffTransport } from './wire-sniffer.js';
 
 export type ServerFactory = () => McpServer | Server;
 
+/**
+ * A factory that optionally consumes the createMcpHandler per-request context.
+ * The context is only supplied on the entry arms (where the entry constructs a
+ * fresh instance per request); on every other arm the factory is called with no
+ * arguments, so declare the parameter optional.
+ */
+export type EntryServerFactory = (ctx?: McpRequestContext) => McpServer | Server;
+
+/** One HTTP exchange recorded by the entry arms (see {@linkcode Wired.httpLog}). */
+export interface RecordedHttpExchange {
+ /** HTTP request method (GET/POST/DELETE). */
+ method: string;
+ /** The request body text, when one was sent as a string. */
+ requestBody?: string;
+ /** HTTP response status. */
+ status: number;
+ /** Response content-type header (empty string when absent). */
+ contentType: string;
+ /** An unread clone of the HTTP response, for byte-level assertions (`await exchange.response.text()`). */
+ response: Response;
+}
+
 export interface Wired extends AsyncDisposable {
  readonly fetch?: (url: URL | string, init?: RequestInit) => Promise<Response>;
  readonly url?: URL;
+ /**
+ * Every HTTP exchange the wired client performed, in order, including the
+ * connect-time negotiation. Recorded by the createMcpHandler entry arms
+ * only — scenarios on those arms use it to assert raw wire facts (request
+ * bodies, response status/content-type/bytes) that the typed client API
+ * does not expose.
+ */
+ readonly httpLog?: readonly RecordedHttpExchange[];
 }
 
 /**
- * The fourth argument controls the wire-format sniffer (see wire-sniffer.ts):
- * every message the client sends or receives is validated against the SDK's
- * spec-anchored Zod schemas. Tests that intentionally use vendor-extension
- * methods pass `{ allowCustomMethods: true }`; tests that deliberately put
- * malformed MCP on the wire pass `{ strictValidation: false }`.
+ * The fourth argument's sniffer options control the wire-format sniffer (see
+ * wire-sniffer.ts): every message the client sends or receives is validated
+ * against the SDK's spec-anchored Zod schemas. Tests that intentionally use
+ * vendor-extension methods pass `{ allowCustomMethods: true }`; tests that
+ * deliberately put malformed MCP on the wire pass `{ strictValidation: false }`.
+ * `entry` overrides the hosting options of the createMcpHandler entry arms
+ * (ignored by every other transport).
  */
-export async function wire(transport: Transport, makeServer: ServerFactory, client: Client, sniff: SnifferOptions = {}): Promise<Wired> {
+export interface WireOptions extends SnifferOptions {
+ /**
+ * createMcpHandler hosting overrides for the entry arms. Defaults:
+ * `{ legacy: 'stateless' }` on entryStateless (the canonical slot value) and
+ * modern-only strict (no legacy slot) on entryModern. `onerror` and
+ * `responseMode` pass through unchanged.
+ */
+ entry?: CreateMcpHandlerOptions;
+}
+
+export async function wire(
+ transport: Transport,
+ makeServer: ServerFactory | EntryServerFactory,
+ client: Client,
+ sniff: WireOptions = {}
+): Promise<Wired> {
  switch (transport) {
  case 'inMemory': {
  const server = makeServer();
@@ -67,6 +130,47 @@ export async function wire(transport: Transport, makeServer: ServerFactory, clie
  [Symbol.asyncDispose]: () => Promise.all([client.close(), handle.close()]).then(() => {})
  };
  }
+ case 'entryStateless':
+ case 'entryModern': {
+ // The dual-era HTTP entry (`createMcpHandler`) hosted in process via an
+ // injected fetch, exactly like the other HTTP arms. The scenario factory
+ // backs the entry directly (the entry calls it once per request with its
+ // per-request context). `entryStateless` serves the scenario's plain
+ // client through the entry's `legacy: 'stateless'` slot; `entryModern`
+ // keeps the endpoint modern-only strict and connects the client on the
+ // 2026-07-28 revision (pin-mode negotiation + the per-request envelope
+ // stop-gap). Every HTTP exchange is recorded on `httpLog`.
+ const handler = createMcpHandler(
+ makeServer,
+ transport === 'entryStateless' ? { legacy: 'stateless', ...sniff.entry } : { ...sniff.entry }
+ );
+ const url = new URL('http://in-process/mcp');
+ const httpLog: RecordedHttpExchange[] = [];
+ const fetch = async (u: URL | string, init?: RequestInit) => {
+ const request = new Request(u, init);
+ const response = await handler.fetch(request);
+ httpLog.push({
+ method: request.method.toUpperCase(),
+ ...(typeof init?.body === 'string' && { requestBody: init.body }),
+ status: response.status,
+ contentType: response.headers.get('content-type') ?? '',
+ response: response.clone()
+ });
+ return response;
+ };
+ let clientTx = new StreamableHTTPClientTransport(url, { fetch });
+ if (transport === 'entryModern') {
+ pinModernNegotiation(client);
+ clientTx = attachModernEnvelope(clientTx);
+ }
+ await client.connect(sniffTransport(clientTx, 'client', sniff));
+ return {
+ fetch,
+ url,
+ httpLog,
+ [Symbol.asyncDispose]: () => Promise.all([client.close(), handler.close()]).then(() => {})
+ };
+ }
  case 'sse': {
  // The legacy SSE transport needs a real socket: the factory's server is hosted on the
  // shipped SSEServerTransport (@modelcontextprotocol/server-legacy/sse) behind a loopback
@@ -212,6 +316,78 @@ export function hostStateless(makeServer: ServerFactory): { handleRequest: HttpH
  };
 }
 
+// ───────────────────────────────────────────────────────────────────────────────
+// createMcpHandler entry arms (entryStateless / entryModern) — client-side shims
+// ───────────────────────────────────────────────────────────────────────────────
+
+/** The protocol revision the entryModern arm negotiates and claims per request. */
+const MODERN_REVISION: SpecVersion = '2026-07-28';
+
+/**
+ * The per-request `_meta` envelope of a 2026-07-28 request, for scenario bodies
+ * that put raw HTTP requests on the wire (via `wired.fetch`) rather than going
+ * through the wired client. Typed calls through the wired client never need
+ * this — the entryModern arm attaches the envelope itself (see
+ * {@linkcode attachModernEnvelope}).
+ */
+export function modernEnvelopeMeta(clientInfo?: Implementation): Record<string, unknown> {
+ return {
+ [PROTOCOL_VERSION_META_KEY]: MODERN_REVISION,
+ [CLIENT_INFO_META_KEY]: clientInfo ?? { name: 'e2e-entry-client', version: '1.0.0' },
+ [CLIENT_CAPABILITIES_META_KEY]: {}
+ };
+}
+
+/**
+ * Put the (already constructed) scenario client into pinned 2026-07-28
+ * negotiation. Version negotiation is a constructor-only option and the
+ * scenario corpus constructs era-agnostic clients, so the entryModern arm flips
+ * the option on the instance before `connect()` — a harness stop-gap, not a
+ * public API. Clients that already opted into a negotiation mode are left
+ * untouched (their cells deliberately exercise that mode).
+ */
+function pinModernNegotiation(client: Client): void {
+ const internals = client as unknown as { _versionNegotiation?: { mode?: unknown } };
+ internals._versionNegotiation ??= { mode: { pin: MODERN_REVISION } };
+}
+
+/**
+ * The per-request `_meta` envelope stop-gap for the entryModern arm: the
+ * negotiating client only attaches the envelope to its `server/discover` probe
+ * today (automatic per-request emission is a client-side follow-up), so the
+ * harness re-attaches the same envelope to every later request and notification
+ * the scenario's typed calls put on the wire. The envelope is captured from the
+ * probe itself, so it always matches what the client actually claimed; messages
+ * that already carry a protocol-version claim (the probe, or a scenario's
+ * explicitly enveloped request) pass through untouched.
+ *
+ * Applied beneath the wire sniffer and `tapWire`, so recorded traffic shows the
+ * messages exactly as the scenario sent them while the wire carries the
+ * envelope the entry requires.
+ */
+function attachModernEnvelope<T extends SdkTransport>(transport: T): T {
+ let envelope: Record<string, unknown> | undefined;
+ const origSend = transport.send.bind(transport);
+ transport.send = async (message, opts) => {
+ let outbound = message;
+ if ('method' in message) {
+ const params = (message.params ?? {}) as { _meta?: Record<string, unknown> };
+ const meta = params._meta;
+ if (meta?.[PROTOCOL_VERSION_META_KEY] !== undefined) {
+ envelope ??= {
+ [PROTOCOL_VERSION_META_KEY]: meta[PROTOCOL_VERSION_META_KEY],
+ [CLIENT_INFO_META_KEY]: meta[CLIENT_INFO_META_KEY],
+ [CLIENT_CAPABILITIES_META_KEY]: meta[CLIENT_CAPABILITIES_META_KEY]
+ };
+ } else if (envelope !== undefined) {
+ outbound = { ...message, params: { ...params, _meta: { ...envelope, ...meta } } };
+ }
+ }
+ return origSend(outbound, opts);
+ };
+ return transport;
+}
+
 // ───────────────────────────────────────────────────────────────────────────────
 // In-process stdio client — TEST-ONLY
 //

test/e2e/helpers/verifies.ts

@@ -18,11 +18,23 @@
 import { describe, test } from 'vitest';
 
 import { REQUIREMENTS } from '../requirements.js';
-import type { TestArgs } from '../types.js';
-import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS } from '../types.js';
+import type { Requirement, SpecVersion, TestArgs, Transport } from '../types.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from '../types.js';
 
 type TestBody = (args: TestArgs) => Promise<void>;
 
+/** Whether a requirement's `entryExclusions` keep the given entry arm out of its cells. */
+function excludedFromEntryArm(req: Requirement, transport: Transport): boolean {
+ if (!(ENTRY_TRANSPORTS as readonly Transport[]).includes(transport)) return false;
+ return (req.entryExclusions ?? []).some(x => x.arm === undefined || x.arm === transport);
+}
+
+/** Whether a transport arm serves the given spec version (era-fixed arms serve exactly one). */
+function transportServesVersion(transport: Transport, version: SpecVersion): boolean {
+ const versions = TRANSPORT_SPEC_VERSIONS[transport];
+ return versions === undefined || versions.includes(version);
+}
+
 export function verifies(id: string | readonly string[], fn: TestBody, opts?: { title?: string }): void {
  const ids = Array.isArray(id) ? id : [id];
  for (const rid of ids) registerOne(rid, fn, opts);
@@ -33,13 +45,13 @@ function registerOne(id: string, fn: TestBody, opts?: { title?: string }): void
  if (!req) throw new Error(`verifies('${id}'): unknown requirement id`);
  if (req.deferred) throw new Error(`verifies('${id}'): requirement is deferred — drop the deferral or the test`);
 
- const transports = req.transports ?? ALL_TRANSPORTS;
+ const transports = (req.transports ?? ALL_TRANSPORTS).filter(t => !excludedFromEntryArm(req, t));
  const versions = ALL_SPEC_VERSIONS.filter(
  v =>
  (req.addedInSpecVersion === undefined || v >= req.addedInSpecVersion) &&
  (req.removedInSpecVersion === undefined || v < req.removedInSpecVersion)
  );
- const cells = versions.flatMap(v => transports.map(t => [t, v] as const));
+ const cells = versions.flatMap(v => transports.filter(t => transportServesVersion(t, v)).map(t => [t, v] as const));
 
  describe.each(cells)(`${id} [%s %s]`, (transport, protocolVersion) => {
  const kf = req.knownFailures?.find(

test/e2e/CLAUDE.md

@@ -58,6 +58,26 @@ note: 'stateless hosting has no server→client back-channel'
 `addedInSpecVersion` / `removedInSpecVersion` bound the spec versions a requirement applies to. A behavior changed by a spec release gets a sibling entry: the new entry lists every retired id it replaces in `supersedes` (an array, requires `addedInSpecVersion`), and each retired
 entry points back via `supersededBy` (requires `removedInSpecVersion`). A coverage gate enforces that the links resolve and are exactly symmetric.
 
+## The createMcpHandler entry arms (entryStateless / entryModern)
+
+Two transport arms host the dual-era HTTP entry (`createMcpHandler`) in process via an injected fetch, exactly like the other HTTP arms. They are era-fixed (`TRANSPORT_SPEC_VERSIONS`), so each registers cells on exactly one spec-version axis:
+
+- `entryStateless` — the entry with the `legacy: 'stateless'` slot; the scenario's plain client is served per request through the slot. Cells run on the 2025-11-25 axis only.
+- `entryModern` — the entry modern-only strict (no legacy slot); the scenario's client is put into pinned 2026-07-28 negotiation by the arm and the per-request `_meta` envelope is attached to every outgoing request/notification by the arm (a harness stop-gap until the client
+ emits it itself). Cells run on the 2026-07-28 axis only.
+
+Both arms are part of the default transport list, so unrestricted requirements run through the entry automatically. When a requirement cannot run on an entry arm, annotate it with a machine-readable reason instead of bending the test:
+
+```ts
+entryExclusions: [{ arm: 'entryModern', reason: 'method-not-in-modern-registry' /* optional note */ }];
+```
+
+Omitting `arm` excludes both arms. The reasons (`EntryExclusionReason` in types.ts) are the acceptance checklist for re-admitting cells when the corresponding entry feature lands; a coverage gate rejects annotations that would never have an effect. Requirement families that the
+per-request entry structurally cannot serve at all (server→client requests, sessions/resumability, standalone GET streams, subscriptions) are already expressed through their `transports` restrictions and need no annotation.
+
+Arm-specific helpers: `wire()`'s fourth argument also accepts `entry` (createMcpHandler hosting overrides — e.g. a `responseMode` or a bring-your-own `legacy` slot value), the returned `Wired.httpLog` records every HTTP exchange (request body, status, content-type, a readable
+response clone) for raw wire assertions, factories may accept the optional per-request context (`EntryServerFactory`), and `modernEnvelopeMeta()` builds the envelope for bodies that POST raw 2026-era requests through `wired.fetch`.
+
 ## Running
 
 From the repo root (the suite is the `@modelcontextprotocol/test-e2e` workspace package):

test/e2e/coverage.test.ts

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { expect, test } from 'vitest';
 
 import { REQUIREMENTS } from './requirements.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from './types.js';
 
 const E2E_DIR = path.dirname(fileURLToPath(import.meta.url));
 
@@ -88,6 +89,34 @@ test('every transport-restricted requirement explains why in note', () => {
  expect(missing).toEqual([]);
 });
 
+test('every entryExclusions annotation targets an entry arm the requirement would otherwise run on', () => {
+ const bad: string[] = [];
+ for (const [id, r] of Object.entries(REQUIREMENTS)) {
+ for (const exclusion of r.entryExclusions ?? []) {
+ const arms = exclusion.arm === undefined ? ENTRY_TRANSPORTS : [exclusion.arm];
+ for (const arm of arms) {
+ const transports = r.transports ?? ALL_TRANSPORTS;
+ if (!transports.includes(arm)) {
+ bad.push(`${id}: entryExclusions targets '${arm}', which the requirement's transports never include`);
+ continue;
+ }
+ const versions = ALL_SPEC_VERSIONS.filter(
+ v =>
+ (r.addedInSpecVersion === undefined || v >= r.addedInSpecVersion) &&
+ (r.removedInSpecVersion === undefined || v < r.removedInSpecVersion) &&
+ (TRANSPORT_SPEC_VERSIONS[arm]?.includes(v) ?? true)
+ );
+ if (versions.length === 0) {
+ bad.push(
+ `${id}: entryExclusions targets '${arm}', which registers no cells within the requirement's spec-version bounds`
+ );
+ }
+ }
+ }
+ }
+ expect(bad).toEqual([]);
+});
+
 test('supersedes/supersededBy links are symmetric and resolve', () => {
  const bad: string[] = [];
  for (const [id, req] of Object.entries(REQUIREMENTS)) {

test/e2e/fixtures/dual-era-stdio-server.ts

@@ -0,0 +1,29 @@
+/**
+ * Runnable dual-era stdio MCP server fixture for the dual-era stdio e2e cells.
+ *
+ * `eraSupport: 'dual-era'` is the single declared act on an otherwise ordinary
+ * hand-constructed McpServer connected to the unchanged StdioServerTransport.
+ * Spawned as a real child process (via tsx) by
+ * test/e2e/scenarios/stdio-dual-era.test.ts; exits when its stdin reaches EOF.
+ */
+
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { z } from 'zod/v4';
+
+const server = new McpServer(
+ { name: 'dual-era-stdio-e2e-fixture', version: '1.0.0' },
+ { capabilities: { tools: {} }, eraSupport: 'dual-era' }
+);
+
+server.registerTool(
+ 'echo',
+ {
+ description: 'Echoes the input text back as a text content block.',
+ inputSchema: z.object({ text: z.string() })
+ },
+ ({ text }) => ({ content: [{ type: 'text', text }] })
+);
+
+await server.connect(new StdioServerTransport());
+process.stderr.write('[dual-era-stdio-server] ready\n');

test/e2e/helpers/index.ts

@@ -15,30 +15,93 @@ import { PassThrough } from 'node:stream';
 
 import type { Client } from '@modelcontextprotocol/client';
 import { SSEClientTransport, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
-import type { EventStore, JSONRPCMessage, McpServer, Server } from '@modelcontextprotocol/server';
-import { InMemoryTransport, ReadBuffer, serializeMessage, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY } from '@modelcontextprotocol/core';
+import type {
+ CreateMcpHandlerOptions,
+ EventStore,
+ Implementation,
+ JSONRPCMessage,
+ McpRequestContext,
+ McpServer,
+ Server,
+ Transport as SdkTransport
+} from '@modelcontextprotocol/server';
+import {
+ createMcpHandler,
+ InMemoryTransport,
+ ReadBuffer,
+ serializeMessage,
+ WebStandardStreamableHTTPServerTransport
+} from '@modelcontextprotocol/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 
-import type { Transport } from '../types.js';
+import type { SpecVersion, Transport } from '../types.js';
 import { startLegacySseHost } from './sse-host.js';
 import type { SnifferOptions } from './wire-sniffer.js';
 import { sniffTransport } from './wire-sniffer.js';
 
 export type ServerFactory = () => McpServer | Server;
 
+/**
+ * A factory that optionally consumes the createMcpHandler per-request context.
+ * The context is only supplied on the entry arms (where the entry constructs a
+ * fresh instance per request); on every other arm the factory is called with no
+ * arguments, so declare the parameter optional.
+ */
+export type EntryServerFactory = (ctx?: McpRequestContext) => McpServer | Server;
+
+/** One HTTP exchange recorded by the entry arms (see {@linkcode Wired.httpLog}). */
+export interface RecordedHttpExchange {
+ /** HTTP request method (GET/POST/DELETE). */
+ method: string;
+ /** The request body text, when one was sent as a string. */
+ requestBody?: string;
+ /** HTTP response status. */
+ status: number;
+ /** Response content-type header (empty string when absent). */
+ contentType: string;
+ /** An unread clone of the HTTP response, for byte-level assertions (`await exchange.response.text()`). */
+ response: Response;
+}
+
 export interface Wired extends AsyncDisposable {
  readonly fetch?: (url: URL | string, init?: RequestInit) => Promise<Response>;
  readonly url?: URL;
+ /**
+ * Every HTTP exchange the wired client performed, in order, including the
+ * connect-time negotiation. Recorded by the createMcpHandler entry arms
+ * only — scenarios on those arms use it to assert raw wire facts (request
+ * bodies, response status/content-type/bytes) that the typed client API
+ * does not expose.
+ */
+ readonly httpLog?: readonly RecordedHttpExchange[];
 }
 
 /**
- * The fourth argument controls the wire-format sniffer (see wire-sniffer.ts):
- * every message the client sends or receives is validated against the SDK's
- * spec-anchored Zod schemas. Tests that intentionally use vendor-extension
- * methods pass `{ allowCustomMethods: true }`; tests that deliberately put
- * malformed MCP on the wire pass `{ strictValidation: false }`.
+ * The fourth argument's sniffer options control the wire-format sniffer (see
+ * wire-sniffer.ts): every message the client sends or receives is validated
+ * against the SDK's spec-anchored Zod schemas. Tests that intentionally use
+ * vendor-extension methods pass `{ allowCustomMethods: true }`; tests that
+ * deliberately put malformed MCP on the wire pass `{ strictValidation: false }`.
+ * `entry` overrides the hosting options of the createMcpHandler entry arms
+ * (ignored by every other transport).
  */
-export async function wire(transport: Transport, makeServer: ServerFactory, client: Client, sniff: SnifferOptions = {}): Promise<Wired> {
+export interface WireOptions extends SnifferOptions {
+ /**
+ * createMcpHandler hosting overrides for the entry arms. Defaults:
+ * `{ legacy: 'stateless' }` on entryStateless (the canonical slot value) and
+ * modern-only strict (no legacy slot) on entryModern. `onerror` and
+ * `responseMode` pass through unchanged.
+ */
+ entry?: CreateMcpHandlerOptions;
+}
+
+export async function wire(
+ transport: Transport,
+ makeServer: ServerFactory | EntryServerFactory,
+ client: Client,
+ sniff: WireOptions = {}
+): Promise<Wired> {
  switch (transport) {
  case 'inMemory': {
  const server = makeServer();
@@ -67,6 +130,47 @@ export async function wire(transport: Transport, makeServer: ServerFactory, clie
  [Symbol.asyncDispose]: () => Promise.all([client.close(), handle.close()]).then(() => {})
  };
  }
+ case 'entryStateless':
+ case 'entryModern': {
+ // The dual-era HTTP entry (`createMcpHandler`) hosted in process via an
+ // injected fetch, exactly like the other HTTP arms. The scenario factory
+ // backs the entry directly (the entry calls it once per request with its
+ // per-request context). `entryStateless` serves the scenario's plain
+ // client through the entry's `legacy: 'stateless'` slot; `entryModern`
+ // keeps the endpoint modern-only strict and connects the client on the
+ // 2026-07-28 revision (pin-mode negotiation + the per-request envelope
+ // stop-gap). Every HTTP exchange is recorded on `httpLog`.
+ const handler = createMcpHandler(
+ makeServer,
+ transport === 'entryStateless' ? { legacy: 'stateless', ...sniff.entry } : { ...sniff.entry }
+ );
+ const url = new URL('http://in-process/mcp');
+ const httpLog: RecordedHttpExchange[] = [];
+ const fetch = async (u: URL | string, init?: RequestInit) => {
+ const request = new Request(u, init);
+ const response = await handler.fetch(request);
+ httpLog.push({
+ method: request.method.toUpperCase(),
+ ...(typeof init?.body === 'string' && { requestBody: init.body }),
+ status: response.status,
+ contentType: response.headers.get('content-type') ?? '',
+ response: response.clone()
+ });
+ return response;
+ };
+ let clientTx = new StreamableHTTPClientTransport(url, { fetch });
+ if (transport === 'entryModern') {
+ pinModernNegotiation(client);
+ clientTx = attachModernEnvelope(clientTx);
+ }
+ await client.connect(sniffTransport(clientTx, 'client', sniff));
+ return {
+ fetch,
+ url,
+ httpLog,
+ [Symbol.asyncDispose]: () => Promise.all([client.close(), handler.close()]).then(() => {})
+ };
+ }
  case 'sse': {
  // The legacy SSE transport needs a real socket: the factory's server is hosted on the
  // shipped SSEServerTransport (@modelcontextprotocol/server-legacy/sse) behind a loopback
@@ -212,6 +316,78 @@ export function hostStateless(makeServer: ServerFactory): { handleRequest: HttpH
  };
 }
 
+// ───────────────────────────────────────────────────────────────────────────────
+// createMcpHandler entry arms (entryStateless / entryModern) — client-side shims
+// ───────────────────────────────────────────────────────────────────────────────
+
+/** The protocol revision the entryModern arm negotiates and claims per request. */
+const MODERN_REVISION: SpecVersion = '2026-07-28';
+
+/**
+ * The per-request `_meta` envelope of a 2026-07-28 request, for scenario bodies
+ * that put raw HTTP requests on the wire (via `wired.fetch`) rather than going
+ * through the wired client. Typed calls through the wired client never need
+ * this — the entryModern arm attaches the envelope itself (see
+ * {@linkcode attachModernEnvelope}).
+ */
+export function modernEnvelopeMeta(clientInfo?: Implementation): Record<string, unknown> {
+ return {
+ [PROTOCOL_VERSION_META_KEY]: MODERN_REVISION,
+ [CLIENT_INFO_META_KEY]: clientInfo ?? { name: 'e2e-entry-client', version: '1.0.0' },
+ [CLIENT_CAPABILITIES_META_KEY]: {}
+ };
+}
+
+/**
+ * Put the (already constructed) scenario client into pinned 2026-07-28
+ * negotiation. Version negotiation is a constructor-only option and the
+ * scenario corpus constructs era-agnostic clients, so the entryModern arm flips
+ * the option on the instance before `connect()` — a harness stop-gap, not a
+ * public API. Clients that already opted into a negotiation mode are left
+ * untouched (their cells deliberately exercise that mode).
+ */
+function pinModernNegotiation(client: Client): void {
+ const internals = client as unknown as { _versionNegotiation?: { mode?: unknown } };
+ internals._versionNegotiation ??= { mode: { pin: MODERN_REVISION } };
+}
+
+/**
+ * The per-request `_meta` envelope stop-gap for the entryModern arm: the
+ * negotiating client only attaches the envelope to its `server/discover` probe
+ * today (automatic per-request emission is a client-side follow-up), so the
+ * harness re-attaches the same envelope to every later request and notification
+ * the scenario's typed calls put on the wire. The envelope is captured from the
+ * probe itself, so it always matches what the client actually claimed; messages
+ * that already carry a protocol-version claim (the probe, or a scenario's
+ * explicitly enveloped request) pass through untouched.
+ *
+ * Applied beneath the wire sniffer and `tapWire`, so recorded traffic shows the
+ * messages exactly as the scenario sent them while the wire carries the
+ * envelope the entry requires.
+ */
+function attachModernEnvelope<T extends SdkTransport>(transport: T): T {
+ let envelope: Record<string, unknown> | undefined;
+ const origSend = transport.send.bind(transport);
+ transport.send = async (message, opts) => {
+ let outbound = message;
+ if ('method' in message) {
+ const params = (message.params ?? {}) as { _meta?: Record<string, unknown> };
+ const meta = params._meta;
+ if (meta?.[PROTOCOL_VERSION_META_KEY] !== undefined) {
+ envelope ??= {
+ [PROTOCOL_VERSION_META_KEY]: meta[PROTOCOL_VERSION_META_KEY],
+ [CLIENT_INFO_META_KEY]: meta[CLIENT_INFO_META_KEY],
+ [CLIENT_CAPABILITIES_META_KEY]: meta[CLIENT_CAPABILITIES_META_KEY]
+ };
+ } else if (envelope !== undefined) {
+ outbound = { ...message, params: { ...params, _meta: { ...envelope, ...meta } } };
+ }
+ }
+ return origSend(outbound, opts);
+ };
+ return transport;
+}
+
 // ───────────────────────────────────────────────────────────────────────────────
 // In-process stdio client — TEST-ONLY
 //

test/e2e/helpers/verifies.ts

@@ -18,11 +18,23 @@
 import { describe, test } from 'vitest';
 
 import { REQUIREMENTS } from '../requirements.js';
-import type { TestArgs } from '../types.js';
-import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS } from '../types.js';
+import type { Requirement, SpecVersion, TestArgs, Transport } from '../types.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from '../types.js';
 
 type TestBody = (args: TestArgs) => Promise<void>;
 
+/** Whether a requirement's `entryExclusions` keep the given entry arm out of its cells. */
+function excludedFromEntryArm(req: Requirement, transport: Transport): boolean {
+ if (!(ENTRY_TRANSPORTS as readonly Transport[]).includes(transport)) return false;
+ return (req.entryExclusions ?? []).some(x => x.arm === undefined || x.arm === transport);
+}
+
+/** Whether a transport arm serves the given spec version (era-fixed arms serve exactly one). */
+function transportServesVersion(transport: Transport, version: SpecVersion): boolean {
+ const versions = TRANSPORT_SPEC_VERSIONS[transport];
+ return versions === undefined || versions.includes(version);
+}
+
 export function verifies(id: string | readonly string[], fn: TestBody, opts?: { title?: string }): void {
  const ids = Array.isArray(id) ? id : [id];
  for (const rid of ids) registerOne(rid, fn, opts);
@@ -33,13 +45,13 @@ function registerOne(id: string, fn: TestBody, opts?: { title?: string }): void
  if (!req) throw new Error(`verifies('${id}'): unknown requirement id`);
  if (req.deferred) throw new Error(`verifies('${id}'): requirement is deferred — drop the deferral or the test`);
 
- const transports = req.transports ?? ALL_TRANSPORTS;
+ const transports = (req.transports ?? ALL_TRANSPORTS).filter(t => !excludedFromEntryArm(req, t));
  const versions = ALL_SPEC_VERSIONS.filter(
  v =>
  (req.addedInSpecVersion === undefined || v >= req.addedInSpecVersion) &&
  (req.removedInSpecVersion === undefined || v < req.removedInSpecVersion)
  );
- const cells = versions.flatMap(v => transports.map(t => [t, v] as const));
+ const cells = versions.flatMap(v => transports.filter(t => transportServesVersion(t, v)).map(t => [t, v] as const));
 
  describe.each(cells)(`${id} [%s %s]`, (transport, protocolVersion) => {
  const kf = req.knownFailures?.find(

test/e2e/CLAUDE.md

@@ -58,6 +58,26 @@ note: 'stateless hosting has no server→client back-channel'
 `addedInSpecVersion` / `removedInSpecVersion` bound the spec versions a requirement applies to. A behavior changed by a spec release gets a sibling entry: the new entry lists every retired id it replaces in `supersedes` (an array, requires `addedInSpecVersion`), and each retired
 entry points back via `supersededBy` (requires `removedInSpecVersion`). A coverage gate enforces that the links resolve and are exactly symmetric.
 
+## The createMcpHandler entry arms (entryStateless / entryModern)
+
+Two transport arms host the dual-era HTTP entry (`createMcpHandler`) in process via an injected fetch, exactly like the other HTTP arms. They are era-fixed (`TRANSPORT_SPEC_VERSIONS`), so each registers cells on exactly one spec-version axis:
+
+- `entryStateless` — the entry with the `legacy: 'stateless'` slot; the scenario's plain client is served per request through the slot. Cells run on the 2025-11-25 axis only.
+- `entryModern` — the entry modern-only strict (no legacy slot); the scenario's client is put into pinned 2026-07-28 negotiation by the arm and the per-request `_meta` envelope is attached to every outgoing request/notification by the arm (a harness stop-gap until the client
+ emits it itself). Cells run on the 2026-07-28 axis only.
+
+Both arms are part of the default transport list, so unrestricted requirements run through the entry automatically. When a requirement cannot run on an entry arm, annotate it with a machine-readable reason instead of bending the test:
+
+```ts
+entryExclusions: [{ arm: 'entryModern', reason: 'method-not-in-modern-registry' /* optional note */ }];
+```
+
+Omitting `arm` excludes both arms. The reasons (`EntryExclusionReason` in types.ts) are the acceptance checklist for re-admitting cells when the corresponding entry feature lands; a coverage gate rejects annotations that would never have an effect. Requirement families that the
+per-request entry structurally cannot serve at all (server→client requests, sessions/resumability, standalone GET streams, subscriptions) are already expressed through their `transports` restrictions and need no annotation.
+
+Arm-specific helpers: `wire()`'s fourth argument also accepts `entry` (createMcpHandler hosting overrides — e.g. a `responseMode` or a bring-your-own `legacy` slot value), the returned `Wired.httpLog` records every HTTP exchange (request body, status, content-type, a readable
+response clone) for raw wire assertions, factories may accept the optional per-request context (`EntryServerFactory`), and `modernEnvelopeMeta()` builds the envelope for bodies that POST raw 2026-era requests through `wired.fetch`.
+
 ## Running
 
 From the repo root (the suite is the `@modelcontextprotocol/test-e2e` workspace package):

test/e2e/coverage.test.ts

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { expect, test } from 'vitest';
 
 import { REQUIREMENTS } from './requirements.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from './types.js';
 
 const E2E_DIR = path.dirname(fileURLToPath(import.meta.url));
 
@@ -88,6 +89,34 @@ test('every transport-restricted requirement explains why in note', () => {
  expect(missing).toEqual([]);
 });
 
+test('every entryExclusions annotation targets an entry arm the requirement would otherwise run on', () => {
+ const bad: string[] = [];
+ for (const [id, r] of Object.entries(REQUIREMENTS)) {
+ for (const exclusion of r.entryExclusions ?? []) {
+ const arms = exclusion.arm === undefined ? ENTRY_TRANSPORTS : [exclusion.arm];
+ for (const arm of arms) {
+ const transports = r.transports ?? ALL_TRANSPORTS;
+ if (!transports.includes(arm)) {
+ bad.push(`${id}: entryExclusions targets '${arm}', which the requirement's transports never include`);
+ continue;
+ }
+ const versions = ALL_SPEC_VERSIONS.filter(
+ v =>
+ (r.addedInSpecVersion === undefined || v >= r.addedInSpecVersion) &&
+ (r.removedInSpecVersion === undefined || v < r.removedInSpecVersion) &&
+ (TRANSPORT_SPEC_VERSIONS[arm]?.includes(v) ?? true)
+ );
+ if (versions.length === 0) {
+ bad.push(
+ `${id}: entryExclusions targets '${arm}', which registers no cells within the requirement's spec-version bounds`
+ );
+ }
+ }
+ }
+ }
+ expect(bad).toEqual([]);
+});
+
 test('supersedes/supersededBy links are symmetric and resolve', () => {
  const bad: string[] = [];
  for (const [id, req] of Object.entries(REQUIREMENTS)) {

test/e2e/fixtures/dual-era-stdio-server.ts

@@ -0,0 +1,29 @@
+/**
+ * Runnable dual-era stdio MCP server fixture for the dual-era stdio e2e cells.
+ *
+ * `eraSupport: 'dual-era'` is the single declared act on an otherwise ordinary
+ * hand-constructed McpServer connected to the unchanged StdioServerTransport.
+ * Spawned as a real child process (via tsx) by
+ * test/e2e/scenarios/stdio-dual-era.test.ts; exits when its stdin reaches EOF.
+ */
+
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { z } from 'zod/v4';
+
+const server = new McpServer(
+ { name: 'dual-era-stdio-e2e-fixture', version: '1.0.0' },
+ { capabilities: { tools: {} }, eraSupport: 'dual-era' }
+);
+
+server.registerTool(
+ 'echo',
+ {
+ description: 'Echoes the input text back as a text content block.',
+ inputSchema: z.object({ text: z.string() })
+ },
+ ({ text }) => ({ content: [{ type: 'text', text }] })
+);
+
+await server.connect(new StdioServerTransport());
+process.stderr.write('[dual-era-stdio-server] ready\n');

test/e2e/helpers/index.ts

@@ -15,30 +15,93 @@ import { PassThrough } from 'node:stream';
 
 import type { Client } from '@modelcontextprotocol/client';
 import { SSEClientTransport, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
-import type { EventStore, JSONRPCMessage, McpServer, Server } from '@modelcontextprotocol/server';
-import { InMemoryTransport, ReadBuffer, serializeMessage, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY } from '@modelcontextprotocol/core';
+import type {
+ CreateMcpHandlerOptions,
+ EventStore,
+ Implementation,
+ JSONRPCMessage,
+ McpRequestContext,
+ McpServer,
+ Server,
+ Transport as SdkTransport
+} from '@modelcontextprotocol/server';
+import {
+ createMcpHandler,
+ InMemoryTransport,
+ ReadBuffer,
+ serializeMessage,
+ WebStandardStreamableHTTPServerTransport
+} from '@modelcontextprotocol/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 
-import type { Transport } from '../types.js';
+import type { SpecVersion, Transport } from '../types.js';
 import { startLegacySseHost } from './sse-host.js';
 import type { SnifferOptions } from './wire-sniffer.js';
 import { sniffTransport } from './wire-sniffer.js';
 
 export type ServerFactory = () => McpServer | Server;
 
+/**
+ * A factory that optionally consumes the createMcpHandler per-request context.
+ * The context is only supplied on the entry arms (where the entry constructs a
+ * fresh instance per request); on every other arm the factory is called with no
+ * arguments, so declare the parameter optional.
+ */
+export type EntryServerFactory = (ctx?: McpRequestContext) => McpServer | Server;
+
+/** One HTTP exchange recorded by the entry arms (see {@linkcode Wired.httpLog}). */
+export interface RecordedHttpExchange {
+ /** HTTP request method (GET/POST/DELETE). */
+ method: string;
+ /** The request body text, when one was sent as a string. */
+ requestBody?: string;
+ /** HTTP response status. */
+ status: number;
+ /** Response content-type header (empty string when absent). */
+ contentType: string;
+ /** An unread clone of the HTTP response, for byte-level assertions (`await exchange.response.text()`). */
+ response: Response;
+}
+
 export interface Wired extends AsyncDisposable {
  readonly fetch?: (url: URL | string, init?: RequestInit) => Promise<Response>;
  readonly url?: URL;
+ /**
+ * Every HTTP exchange the wired client performed, in order, including the
+ * connect-time negotiation. Recorded by the createMcpHandler entry arms
+ * only — scenarios on those arms use it to assert raw wire facts (request
+ * bodies, response status/content-type/bytes) that the typed client API
+ * does not expose.
+ */
+ readonly httpLog?: readonly RecordedHttpExchange[];
 }
 
 /**
- * The fourth argument controls the wire-format sniffer (see wire-sniffer.ts):
- * every message the client sends or receives is validated against the SDK's
- * spec-anchored Zod schemas. Tests that intentionally use vendor-extension
- * methods pass `{ allowCustomMethods: true }`; tests that deliberately put
- * malformed MCP on the wire pass `{ strictValidation: false }`.
+ * The fourth argument's sniffer options control the wire-format sniffer (see
+ * wire-sniffer.ts): every message the client sends or receives is validated
+ * against the SDK's spec-anchored Zod schemas. Tests that intentionally use
+ * vendor-extension methods pass `{ allowCustomMethods: true }`; tests that
+ * deliberately put malformed MCP on the wire pass `{ strictValidation: false }`.
+ * `entry` overrides the hosting options of the createMcpHandler entry arms
+ * (ignored by every other transport).
  */
-export async function wire(transport: Transport, makeServer: ServerFactory, client: Client, sniff: SnifferOptions = {}): Promise<Wired> {
+export interface WireOptions extends SnifferOptions {
+ /**
+ * createMcpHandler hosting overrides for the entry arms. Defaults:
+ * `{ legacy: 'stateless' }` on entryStateless (the canonical slot value) and
+ * modern-only strict (no legacy slot) on entryModern. `onerror` and
+ * `responseMode` pass through unchanged.
+ */
+ entry?: CreateMcpHandlerOptions;
+}
+
+export async function wire(
+ transport: Transport,
+ makeServer: ServerFactory | EntryServerFactory,
+ client: Client,
+ sniff: WireOptions = {}
+): Promise<Wired> {
  switch (transport) {
  case 'inMemory': {
  const server = makeServer();
@@ -67,6 +130,47 @@ export async function wire(transport: Transport, makeServer: ServerFactory, clie
  [Symbol.asyncDispose]: () => Promise.all([client.close(), handle.close()]).then(() => {})
  };
  }
+ case 'entryStateless':
+ case 'entryModern': {
+ // The dual-era HTTP entry (`createMcpHandler`) hosted in process via an
+ // injected fetch, exactly like the other HTTP arms. The scenario factory
+ // backs the entry directly (the entry calls it once per request with its
+ // per-request context). `entryStateless` serves the scenario's plain
+ // client through the entry's `legacy: 'stateless'` slot; `entryModern`
+ // keeps the endpoint modern-only strict and connects the client on the
+ // 2026-07-28 revision (pin-mode negotiation + the per-request envelope
+ // stop-gap). Every HTTP exchange is recorded on `httpLog`.
+ const handler = createMcpHandler(
+ makeServer,
+ transport === 'entryStateless' ? { legacy: 'stateless', ...sniff.entry } : { ...sniff.entry }
+ );
+ const url = new URL('http://in-process/mcp');
+ const httpLog: RecordedHttpExchange[] = [];
+ const fetch = async (u: URL | string, init?: RequestInit) => {
+ const request = new Request(u, init);
+ const response = await handler.fetch(request);
+ httpLog.push({
+ method: request.method.toUpperCase(),
+ ...(typeof init?.body === 'string' && { requestBody: init.body }),
+ status: response.status,
+ contentType: response.headers.get('content-type') ?? '',
+ response: response.clone()
+ });
+ return response;
+ };
+ let clientTx = new StreamableHTTPClientTransport(url, { fetch });
+ if (transport === 'entryModern') {
+ pinModernNegotiation(client);
+ clientTx = attachModernEnvelope(clientTx);
+ }
+ await client.connect(sniffTransport(clientTx, 'client', sniff));
+ return {
+ fetch,
+ url,
+ httpLog,
+ [Symbol.asyncDispose]: () => Promise.all([client.close(), handler.close()]).then(() => {})
+ };
+ }
  case 'sse': {
  // The legacy SSE transport needs a real socket: the factory's server is hosted on the
  // shipped SSEServerTransport (@modelcontextprotocol/server-legacy/sse) behind a loopback
@@ -212,6 +316,78 @@ export function hostStateless(makeServer: ServerFactory): { handleRequest: HttpH
  };
 }
 
+// ───────────────────────────────────────────────────────────────────────────────
+// createMcpHandler entry arms (entryStateless / entryModern) — client-side shims
+// ───────────────────────────────────────────────────────────────────────────────
+
+/** The protocol revision the entryModern arm negotiates and claims per request. */
+const MODERN_REVISION: SpecVersion = '2026-07-28';
+
+/**
+ * The per-request `_meta` envelope of a 2026-07-28 request, for scenario bodies
+ * that put raw HTTP requests on the wire (via `wired.fetch`) rather than going
+ * through the wired client. Typed calls through the wired client never need
+ * this — the entryModern arm attaches the envelope itself (see
+ * {@linkcode attachModernEnvelope}).
+ */
+export function modernEnvelopeMeta(clientInfo?: Implementation): Record<string, unknown> {
+ return {
+ [PROTOCOL_VERSION_META_KEY]: MODERN_REVISION,
+ [CLIENT_INFO_META_KEY]: clientInfo ?? { name: 'e2e-entry-client', version: '1.0.0' },
+ [CLIENT_CAPABILITIES_META_KEY]: {}
+ };
+}
+
+/**
+ * Put the (already constructed) scenario client into pinned 2026-07-28
+ * negotiation. Version negotiation is a constructor-only option and the
+ * scenario corpus constructs era-agnostic clients, so the entryModern arm flips
+ * the option on the instance before `connect()` — a harness stop-gap, not a
+ * public API. Clients that already opted into a negotiation mode are left
+ * untouched (their cells deliberately exercise that mode).
+ */
+function pinModernNegotiation(client: Client): void {
+ const internals = client as unknown as { _versionNegotiation?: { mode?: unknown } };
+ internals._versionNegotiation ??= { mode: { pin: MODERN_REVISION } };
+}
+
+/**
+ * The per-request `_meta` envelope stop-gap for the entryModern arm: the
+ * negotiating client only attaches the envelope to its `server/discover` probe
+ * today (automatic per-request emission is a client-side follow-up), so the
+ * harness re-attaches the same envelope to every later request and notification
+ * the scenario's typed calls put on the wire. The envelope is captured from the
+ * probe itself, so it always matches what the client actually claimed; messages
+ * that already carry a protocol-version claim (the probe, or a scenario's
+ * explicitly enveloped request) pass through untouched.
+ *
+ * Applied beneath the wire sniffer and `tapWire`, so recorded traffic shows the
+ * messages exactly as the scenario sent them while the wire carries the
+ * envelope the entry requires.
+ */
+function attachModernEnvelope<T extends SdkTransport>(transport: T): T {
+ let envelope: Record<string, unknown> | undefined;
+ const origSend = transport.send.bind(transport);
+ transport.send = async (message, opts) => {
+ let outbound = message;
+ if ('method' in message) {
+ const params = (message.params ?? {}) as { _meta?: Record<string, unknown> };
+ const meta = params._meta;
+ if (meta?.[PROTOCOL_VERSION_META_KEY] !== undefined) {
+ envelope ??= {
+ [PROTOCOL_VERSION_META_KEY]: meta[PROTOCOL_VERSION_META_KEY],
+ [CLIENT_INFO_META_KEY]: meta[CLIENT_INFO_META_KEY],
+ [CLIENT_CAPABILITIES_META_KEY]: meta[CLIENT_CAPABILITIES_META_KEY]
+ };
+ } else if (envelope !== undefined) {
+ outbound = { ...message, params: { ...params, _meta: { ...envelope, ...meta } } };
+ }
+ }
+ return origSend(outbound, opts);
+ };
+ return transport;
+}
+
 // ───────────────────────────────────────────────────────────────────────────────
 // In-process stdio client — TEST-ONLY
 //

test/e2e/helpers/verifies.ts

@@ -18,11 +18,23 @@
 import { describe, test } from 'vitest';
 
 import { REQUIREMENTS } from '../requirements.js';
-import type { TestArgs } from '../types.js';
-import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS } from '../types.js';
+import type { Requirement, SpecVersion, TestArgs, Transport } from '../types.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from '../types.js';
 
 type TestBody = (args: TestArgs) => Promise<void>;
 
+/** Whether a requirement's `entryExclusions` keep the given entry arm out of its cells. */
+function excludedFromEntryArm(req: Requirement, transport: Transport): boolean {
+ if (!(ENTRY_TRANSPORTS as readonly Transport[]).includes(transport)) return false;
+ return (req.entryExclusions ?? []).some(x => x.arm === undefined || x.arm === transport);
+}
+
+/** Whether a transport arm serves the given spec version (era-fixed arms serve exactly one). */
+function transportServesVersion(transport: Transport, version: SpecVersion): boolean {
+ const versions = TRANSPORT_SPEC_VERSIONS[transport];
+ return versions === undefined || versions.includes(version);
+}
+
 export function verifies(id: string | readonly string[], fn: TestBody, opts?: { title?: string }): void {
  const ids = Array.isArray(id) ? id : [id];
  for (const rid of ids) registerOne(rid, fn, opts);
@@ -33,13 +45,13 @@ function registerOne(id: string, fn: TestBody, opts?: { title?: string }): void
  if (!req) throw new Error(`verifies('${id}'): unknown requirement id`);
  if (req.deferred) throw new Error(`verifies('${id}'): requirement is deferred — drop the deferral or the test`);
 
- const transports = req.transports ?? ALL_TRANSPORTS;
+ const transports = (req.transports ?? ALL_TRANSPORTS).filter(t => !excludedFromEntryArm(req, t));
  const versions = ALL_SPEC_VERSIONS.filter(
  v =>
  (req.addedInSpecVersion === undefined || v >= req.addedInSpecVersion) &&
  (req.removedInSpecVersion === undefined || v < req.removedInSpecVersion)
  );
- const cells = versions.flatMap(v => transports.map(t => [t, v] as const));
+ const cells = versions.flatMap(v => transports.filter(t => transportServesVersion(t, v)).map(t => [t, v] as const));
 
  describe.each(cells)(`${id} [%s %s]`, (transport, protocolVersion) => {
  const kf = req.knownFailures?.find(

test/e2e/CLAUDE.md

@@ -58,6 +58,26 @@ note: 'stateless hosting has no server→client back-channel'
 `addedInSpecVersion` / `removedInSpecVersion` bound the spec versions a requirement applies to. A behavior changed by a spec release gets a sibling entry: the new entry lists every retired id it replaces in `supersedes` (an array, requires `addedInSpecVersion`), and each retired
 entry points back via `supersededBy` (requires `removedInSpecVersion`). A coverage gate enforces that the links resolve and are exactly symmetric.
 
+## The createMcpHandler entry arms (entryStateless / entryModern)
+
+Two transport arms host the dual-era HTTP entry (`createMcpHandler`) in process via an injected fetch, exactly like the other HTTP arms. They are era-fixed (`TRANSPORT_SPEC_VERSIONS`), so each registers cells on exactly one spec-version axis:
+
+- `entryStateless` — the entry with the `legacy: 'stateless'` slot; the scenario's plain client is served per request through the slot. Cells run on the 2025-11-25 axis only.
+- `entryModern` — the entry modern-only strict (no legacy slot); the scenario's client is put into pinned 2026-07-28 negotiation by the arm and the per-request `_meta` envelope is attached to every outgoing request/notification by the arm (a harness stop-gap until the client
+ emits it itself). Cells run on the 2026-07-28 axis only.
+
+Both arms are part of the default transport list, so unrestricted requirements run through the entry automatically. When a requirement cannot run on an entry arm, annotate it with a machine-readable reason instead of bending the test:
+
+```ts
+entryExclusions: [{ arm: 'entryModern', reason: 'method-not-in-modern-registry' /* optional note */ }];
+```
+
+Omitting `arm` excludes both arms. The reasons (`EntryExclusionReason` in types.ts) are the acceptance checklist for re-admitting cells when the corresponding entry feature lands; a coverage gate rejects annotations that would never have an effect. Requirement families that the
+per-request entry structurally cannot serve at all (server→client requests, sessions/resumability, standalone GET streams, subscriptions) are already expressed through their `transports` restrictions and need no annotation.
+
+Arm-specific helpers: `wire()`'s fourth argument also accepts `entry` (createMcpHandler hosting overrides — e.g. a `responseMode` or a bring-your-own `legacy` slot value), the returned `Wired.httpLog` records every HTTP exchange (request body, status, content-type, a readable
+response clone) for raw wire assertions, factories may accept the optional per-request context (`EntryServerFactory`), and `modernEnvelopeMeta()` builds the envelope for bodies that POST raw 2026-era requests through `wired.fetch`.
+
 ## Running
 
 From the repo root (the suite is the `@modelcontextprotocol/test-e2e` workspace package):

test/e2e/coverage.test.ts

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { expect, test } from 'vitest';
 
 import { REQUIREMENTS } from './requirements.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from './types.js';
 
 const E2E_DIR = path.dirname(fileURLToPath(import.meta.url));
 
@@ -88,6 +89,34 @@ test('every transport-restricted requirement explains why in note', () => {
  expect(missing).toEqual([]);
 });
 
+test('every entryExclusions annotation targets an entry arm the requirement would otherwise run on', () => {
+ const bad: string[] = [];
+ for (const [id, r] of Object.entries(REQUIREMENTS)) {
+ for (const exclusion of r.entryExclusions ?? []) {
+ const arms = exclusion.arm === undefined ? ENTRY_TRANSPORTS : [exclusion.arm];
+ for (const arm of arms) {
+ const transports = r.transports ?? ALL_TRANSPORTS;
+ if (!transports.includes(arm)) {
+ bad.push(`${id}: entryExclusions targets '${arm}', which the requirement's transports never include`);
+ continue;
+ }
+ const versions = ALL_SPEC_VERSIONS.filter(
+ v =>
+ (r.addedInSpecVersion === undefined || v >= r.addedInSpecVersion) &&
+ (r.removedInSpecVersion === undefined || v < r.removedInSpecVersion) &&
+ (TRANSPORT_SPEC_VERSIONS[arm]?.includes(v) ?? true)
+ );
+ if (versions.length === 0) {
+ bad.push(
+ `${id}: entryExclusions targets '${arm}', which registers no cells within the requirement's spec-version bounds`
+ );
+ }
+ }
+ }
+ }
+ expect(bad).toEqual([]);
+});
+
 test('supersedes/supersededBy links are symmetric and resolve', () => {
  const bad: string[] = [];
  for (const [id, req] of Object.entries(REQUIREMENTS)) {

test/e2e/fixtures/dual-era-stdio-server.ts

@@ -0,0 +1,29 @@
+/**
+ * Runnable dual-era stdio MCP server fixture for the dual-era stdio e2e cells.
+ *
+ * `eraSupport: 'dual-era'` is the single declared act on an otherwise ordinary
+ * hand-constructed McpServer connected to the unchanged StdioServerTransport.
+ * Spawned as a real child process (via tsx) by
+ * test/e2e/scenarios/stdio-dual-era.test.ts; exits when its stdin reaches EOF.
+ */
+
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { z } from 'zod/v4';
+
+const server = new McpServer(
+ { name: 'dual-era-stdio-e2e-fixture', version: '1.0.0' },
+ { capabilities: { tools: {} }, eraSupport: 'dual-era' }
+);
+
+server.registerTool(
+ 'echo',
+ {
+ description: 'Echoes the input text back as a text content block.',
+ inputSchema: z.object({ text: z.string() })
+ },
+ ({ text }) => ({ content: [{ type: 'text', text }] })
+);
+
+await server.connect(new StdioServerTransport());
+process.stderr.write('[dual-era-stdio-server] ready\n');

test/e2e/helpers/index.ts

@@ -15,30 +15,93 @@ import { PassThrough } from 'node:stream';
 
 import type { Client } from '@modelcontextprotocol/client';
 import { SSEClientTransport, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
-import type { EventStore, JSONRPCMessage, McpServer, Server } from '@modelcontextprotocol/server';
-import { InMemoryTransport, ReadBuffer, serializeMessage, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY } from '@modelcontextprotocol/core';
+import type {
+ CreateMcpHandlerOptions,
+ EventStore,
+ Implementation,
+ JSONRPCMessage,
+ McpRequestContext,
+ McpServer,
+ Server,
+ Transport as SdkTransport
+} from '@modelcontextprotocol/server';
+import {
+ createMcpHandler,
+ InMemoryTransport,
+ ReadBuffer,
+ serializeMessage,
+ WebStandardStreamableHTTPServerTransport
+} from '@modelcontextprotocol/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 
-import type { Transport } from '../types.js';
+import type { SpecVersion, Transport } from '../types.js';
 import { startLegacySseHost } from './sse-host.js';
 import type { SnifferOptions } from './wire-sniffer.js';
 import { sniffTransport } from './wire-sniffer.js';
 
 export type ServerFactory = () => McpServer | Server;
 
+/**
+ * A factory that optionally consumes the createMcpHandler per-request context.
+ * The context is only supplied on the entry arms (where the entry constructs a
+ * fresh instance per request); on every other arm the factory is called with no
+ * arguments, so declare the parameter optional.
+ */
+export type EntryServerFactory = (ctx?: McpRequestContext) => McpServer | Server;
+
+/** One HTTP exchange recorded by the entry arms (see {@linkcode Wired.httpLog}). */
+export interface RecordedHttpExchange {
+ /** HTTP request method (GET/POST/DELETE). */
+ method: string;
+ /** The request body text, when one was sent as a string. */
+ requestBody?: string;
+ /** HTTP response status. */
+ status: number;
+ /** Response content-type header (empty string when absent). */
+ contentType: string;
+ /** An unread clone of the HTTP response, for byte-level assertions (`await exchange.response.text()`). */
+ response: Response;
+}
+
 export interface Wired extends AsyncDisposable {
  readonly fetch?: (url: URL | string, init?: RequestInit) => Promise<Response>;
  readonly url?: URL;
+ /**
+ * Every HTTP exchange the wired client performed, in order, including the
+ * connect-time negotiation. Recorded by the createMcpHandler entry arms
+ * only — scenarios on those arms use it to assert raw wire facts (request
+ * bodies, response status/content-type/bytes) that the typed client API
+ * does not expose.
+ */
+ readonly httpLog?: readonly RecordedHttpExchange[];
 }
 
 /**
- * The fourth argument controls the wire-format sniffer (see wire-sniffer.ts):
- * every message the client sends or receives is validated against the SDK's
- * spec-anchored Zod schemas. Tests that intentionally use vendor-extension
- * methods pass `{ allowCustomMethods: true }`; tests that deliberately put
- * malformed MCP on the wire pass `{ strictValidation: false }`.
+ * The fourth argument's sniffer options control the wire-format sniffer (see
+ * wire-sniffer.ts): every message the client sends or receives is validated
+ * against the SDK's spec-anchored Zod schemas. Tests that intentionally use
+ * vendor-extension methods pass `{ allowCustomMethods: true }`; tests that
+ * deliberately put malformed MCP on the wire pass `{ strictValidation: false }`.
+ * `entry` overrides the hosting options of the createMcpHandler entry arms
+ * (ignored by every other transport).
  */
-export async function wire(transport: Transport, makeServer: ServerFactory, client: Client, sniff: SnifferOptions = {}): Promise<Wired> {
+export interface WireOptions extends SnifferOptions {
+ /**
+ * createMcpHandler hosting overrides for the entry arms. Defaults:
+ * `{ legacy: 'stateless' }` on entryStateless (the canonical slot value) and
+ * modern-only strict (no legacy slot) on entryModern. `onerror` and
+ * `responseMode` pass through unchanged.
+ */
+ entry?: CreateMcpHandlerOptions;
+}
+
+export async function wire(
+ transport: Transport,
+ makeServer: ServerFactory | EntryServerFactory,
+ client: Client,
+ sniff: WireOptions = {}
+): Promise<Wired> {
  switch (transport) {
  case 'inMemory': {
  const server = makeServer();
@@ -67,6 +130,47 @@ export async function wire(transport: Transport, makeServer: ServerFactory, clie
  [Symbol.asyncDispose]: () => Promise.all([client.close(), handle.close()]).then(() => {})
  };
  }
+ case 'entryStateless':
+ case 'entryModern': {
+ // The dual-era HTTP entry (`createMcpHandler`) hosted in process via an
+ // injected fetch, exactly like the other HTTP arms. The scenario factory
+ // backs the entry directly (the entry calls it once per request with its
+ // per-request context). `entryStateless` serves the scenario's plain
+ // client through the entry's `legacy: 'stateless'` slot; `entryModern`
+ // keeps the endpoint modern-only strict and connects the client on the
+ // 2026-07-28 revision (pin-mode negotiation + the per-request envelope
+ // stop-gap). Every HTTP exchange is recorded on `httpLog`.
+ const handler = createMcpHandler(
+ makeServer,
+ transport === 'entryStateless' ? { legacy: 'stateless', ...sniff.entry } : { ...sniff.entry }
+ );
+ const url = new URL('http://in-process/mcp');
+ const httpLog: RecordedHttpExchange[] = [];
+ const fetch = async (u: URL | string, init?: RequestInit) => {
+ const request = new Request(u, init);
+ const response = await handler.fetch(request);
+ httpLog.push({
+ method: request.method.toUpperCase(),
+ ...(typeof init?.body === 'string' && { requestBody: init.body }),
+ status: response.status,
+ contentType: response.headers.get('content-type') ?? '',
+ response: response.clone()
+ });
+ return response;
+ };
+ let clientTx = new StreamableHTTPClientTransport(url, { fetch });
+ if (transport === 'entryModern') {
+ pinModernNegotiation(client);
+ clientTx = attachModernEnvelope(clientTx);
+ }
+ await client.connect(sniffTransport(clientTx, 'client', sniff));
+ return {
+ fetch,
+ url,
+ httpLog,
+ [Symbol.asyncDispose]: () => Promise.all([client.close(), handler.close()]).then(() => {})
+ };
+ }
  case 'sse': {
  // The legacy SSE transport needs a real socket: the factory's server is hosted on the
  // shipped SSEServerTransport (@modelcontextprotocol/server-legacy/sse) behind a loopback
@@ -212,6 +316,78 @@ export function hostStateless(makeServer: ServerFactory): { handleRequest: HttpH
  };
 }
 
+// ───────────────────────────────────────────────────────────────────────────────
+// createMcpHandler entry arms (entryStateless / entryModern) — client-side shims
+// ───────────────────────────────────────────────────────────────────────────────
+
+/** The protocol revision the entryModern arm negotiates and claims per request. */
+const MODERN_REVISION: SpecVersion = '2026-07-28';
+
+/**
+ * The per-request `_meta` envelope of a 2026-07-28 request, for scenario bodies
+ * that put raw HTTP requests on the wire (via `wired.fetch`) rather than going
+ * through the wired client. Typed calls through the wired client never need
+ * this — the entryModern arm attaches the envelope itself (see
+ * {@linkcode attachModernEnvelope}).
+ */
+export function modernEnvelopeMeta(clientInfo?: Implementation): Record<string, unknown> {
+ return {
+ [PROTOCOL_VERSION_META_KEY]: MODERN_REVISION,
+ [CLIENT_INFO_META_KEY]: clientInfo ?? { name: 'e2e-entry-client', version: '1.0.0' },
+ [CLIENT_CAPABILITIES_META_KEY]: {}
+ };
+}
+
+/**
+ * Put the (already constructed) scenario client into pinned 2026-07-28
+ * negotiation. Version negotiation is a constructor-only option and the
+ * scenario corpus constructs era-agnostic clients, so the entryModern arm flips
+ * the option on the instance before `connect()` — a harness stop-gap, not a
+ * public API. Clients that already opted into a negotiation mode are left
+ * untouched (their cells deliberately exercise that mode).
+ */
+function pinModernNegotiation(client: Client): void {
+ const internals = client as unknown as { _versionNegotiation?: { mode?: unknown } };
+ internals._versionNegotiation ??= { mode: { pin: MODERN_REVISION } };
+}
+
+/**
+ * The per-request `_meta` envelope stop-gap for the entryModern arm: the
+ * negotiating client only attaches the envelope to its `server/discover` probe
+ * today (automatic per-request emission is a client-side follow-up), so the
+ * harness re-attaches the same envelope to every later request and notification
+ * the scenario's typed calls put on the wire. The envelope is captured from the
+ * probe itself, so it always matches what the client actually claimed; messages
+ * that already carry a protocol-version claim (the probe, or a scenario's
+ * explicitly enveloped request) pass through untouched.
+ *
+ * Applied beneath the wire sniffer and `tapWire`, so recorded traffic shows the
+ * messages exactly as the scenario sent them while the wire carries the
+ * envelope the entry requires.
+ */
+function attachModernEnvelope<T extends SdkTransport>(transport: T): T {
+ let envelope: Record<string, unknown> | undefined;
+ const origSend = transport.send.bind(transport);
+ transport.send = async (message, opts) => {
+ let outbound = message;
+ if ('method' in message) {
+ const params = (message.params ?? {}) as { _meta?: Record<string, unknown> };
+ const meta = params._meta;
+ if (meta?.[PROTOCOL_VERSION_META_KEY] !== undefined) {
+ envelope ??= {
+ [PROTOCOL_VERSION_META_KEY]: meta[PROTOCOL_VERSION_META_KEY],
+ [CLIENT_INFO_META_KEY]: meta[CLIENT_INFO_META_KEY],
+ [CLIENT_CAPABILITIES_META_KEY]: meta[CLIENT_CAPABILITIES_META_KEY]
+ };
+ } else if (envelope !== undefined) {
+ outbound = { ...message, params: { ...params, _meta: { ...envelope, ...meta } } };
+ }
+ }
+ return origSend(outbound, opts);
+ };
+ return transport;
+}
+
 // ───────────────────────────────────────────────────────────────────────────────
 // In-process stdio client — TEST-ONLY
 //

test/e2e/helpers/verifies.ts

@@ -18,11 +18,23 @@
 import { describe, test } from 'vitest';
 
 import { REQUIREMENTS } from '../requirements.js';
-import type { TestArgs } from '../types.js';
-import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS } from '../types.js';
+import type { Requirement, SpecVersion, TestArgs, Transport } from '../types.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from '../types.js';
 
 type TestBody = (args: TestArgs) => Promise<void>;
 
+/** Whether a requirement's `entryExclusions` keep the given entry arm out of its cells. */
+function excludedFromEntryArm(req: Requirement, transport: Transport): boolean {
+ if (!(ENTRY_TRANSPORTS as readonly Transport[]).includes(transport)) return false;
+ return (req.entryExclusions ?? []).some(x => x.arm === undefined || x.arm === transport);
+}
+
+/** Whether a transport arm serves the given spec version (era-fixed arms serve exactly one). */
+function transportServesVersion(transport: Transport, version: SpecVersion): boolean {
+ const versions = TRANSPORT_SPEC_VERSIONS[transport];
+ return versions === undefined || versions.includes(version);
+}
+
 export function verifies(id: string | readonly string[], fn: TestBody, opts?: { title?: string }): void {
  const ids = Array.isArray(id) ? id : [id];
  for (const rid of ids) registerOne(rid, fn, opts);
@@ -33,13 +45,13 @@ function registerOne(id: string, fn: TestBody, opts?: { title?: string }): void
  if (!req) throw new Error(`verifies('${id}'): unknown requirement id`);
  if (req.deferred) throw new Error(`verifies('${id}'): requirement is deferred — drop the deferral or the test`);
 
- const transports = req.transports ?? ALL_TRANSPORTS;
+ const transports = (req.transports ?? ALL_TRANSPORTS).filter(t => !excludedFromEntryArm(req, t));
  const versions = ALL_SPEC_VERSIONS.filter(
  v =>
  (req.addedInSpecVersion === undefined || v >= req.addedInSpecVersion) &&
  (req.removedInSpecVersion === undefined || v < req.removedInSpecVersion)
  );
- const cells = versions.flatMap(v => transports.map(t => [t, v] as const));
+ const cells = versions.flatMap(v => transports.filter(t => transportServesVersion(t, v)).map(t => [t, v] as const));
 
  describe.each(cells)(`${id} [%s %s]`, (transport, protocolVersion) => {
  const kf = req.knownFailures?.find(

test/e2e/CLAUDE.md

@@ -58,6 +58,26 @@ note: 'stateless hosting has no server→client back-channel'
 `addedInSpecVersion` / `removedInSpecVersion` bound the spec versions a requirement applies to. A behavior changed by a spec release gets a sibling entry: the new entry lists every retired id it replaces in `supersedes` (an array, requires `addedInSpecVersion`), and each retired
 entry points back via `supersededBy` (requires `removedInSpecVersion`). A coverage gate enforces that the links resolve and are exactly symmetric.
 
+## The createMcpHandler entry arms (entryStateless / entryModern)
+
+Two transport arms host the dual-era HTTP entry (`createMcpHandler`) in process via an injected fetch, exactly like the other HTTP arms. They are era-fixed (`TRANSPORT_SPEC_VERSIONS`), so each registers cells on exactly one spec-version axis:
+
+- `entryStateless` — the entry with the `legacy: 'stateless'` slot; the scenario's plain client is served per request through the slot. Cells run on the 2025-11-25 axis only.
+- `entryModern` — the entry modern-only strict (no legacy slot); the scenario's client is put into pinned 2026-07-28 negotiation by the arm and the per-request `_meta` envelope is attached to every outgoing request/notification by the arm (a harness stop-gap until the client
+ emits it itself). Cells run on the 2026-07-28 axis only.
+
+Both arms are part of the default transport list, so unrestricted requirements run through the entry automatically. When a requirement cannot run on an entry arm, annotate it with a machine-readable reason instead of bending the test:
+
+```ts
+entryExclusions: [{ arm: 'entryModern', reason: 'method-not-in-modern-registry' /* optional note */ }];
+```
+
+Omitting `arm` excludes both arms. The reasons (`EntryExclusionReason` in types.ts) are the acceptance checklist for re-admitting cells when the corresponding entry feature lands; a coverage gate rejects annotations that would never have an effect. Requirement families that the
+per-request entry structurally cannot serve at all (server→client requests, sessions/resumability, standalone GET streams, subscriptions) are already expressed through their `transports` restrictions and need no annotation.
+
+Arm-specific helpers: `wire()`'s fourth argument also accepts `entry` (createMcpHandler hosting overrides — e.g. a `responseMode` or a bring-your-own `legacy` slot value), the returned `Wired.httpLog` records every HTTP exchange (request body, status, content-type, a readable
+response clone) for raw wire assertions, factories may accept the optional per-request context (`EntryServerFactory`), and `modernEnvelopeMeta()` builds the envelope for bodies that POST raw 2026-era requests through `wired.fetch`.
+
 ## Running
 
 From the repo root (the suite is the `@modelcontextprotocol/test-e2e` workspace package):

test/e2e/coverage.test.ts

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { expect, test } from 'vitest';
 
 import { REQUIREMENTS } from './requirements.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from './types.js';
 
 const E2E_DIR = path.dirname(fileURLToPath(import.meta.url));
 
@@ -88,6 +89,34 @@ test('every transport-restricted requirement explains why in note', () => {
  expect(missing).toEqual([]);
 });
 
+test('every entryExclusions annotation targets an entry arm the requirement would otherwise run on', () => {
+ const bad: string[] = [];
+ for (const [id, r] of Object.entries(REQUIREMENTS)) {
+ for (const exclusion of r.entryExclusions ?? []) {
+ const arms = exclusion.arm === undefined ? ENTRY_TRANSPORTS : [exclusion.arm];
+ for (const arm of arms) {
+ const transports = r.transports ?? ALL_TRANSPORTS;
+ if (!transports.includes(arm)) {
+ bad.push(`${id}: entryExclusions targets '${arm}', which the requirement's transports never include`);
+ continue;
+ }
+ const versions = ALL_SPEC_VERSIONS.filter(
+ v =>
+ (r.addedInSpecVersion === undefined || v >= r.addedInSpecVersion) &&
+ (r.removedInSpecVersion === undefined || v < r.removedInSpecVersion) &&
+ (TRANSPORT_SPEC_VERSIONS[arm]?.includes(v) ?? true)
+ );
+ if (versions.length === 0) {
+ bad.push(
+ `${id}: entryExclusions targets '${arm}', which registers no cells within the requirement's spec-version bounds`
+ );
+ }
+ }
+ }
+ }
+ expect(bad).toEqual([]);
+});
+
 test('supersedes/supersededBy links are symmetric and resolve', () => {
  const bad: string[] = [];
  for (const [id, req] of Object.entries(REQUIREMENTS)) {

test/e2e/fixtures/dual-era-stdio-server.ts

@@ -0,0 +1,29 @@
+/**
+ * Runnable dual-era stdio MCP server fixture for the dual-era stdio e2e cells.
+ *
+ * `eraSupport: 'dual-era'` is the single declared act on an otherwise ordinary
+ * hand-constructed McpServer connected to the unchanged StdioServerTransport.
+ * Spawned as a real child process (via tsx) by
+ * test/e2e/scenarios/stdio-dual-era.test.ts; exits when its stdin reaches EOF.
+ */
+
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { z } from 'zod/v4';
+
+const server = new McpServer(
+ { name: 'dual-era-stdio-e2e-fixture', version: '1.0.0' },
+ { capabilities: { tools: {} }, eraSupport: 'dual-era' }
+);
+
+server.registerTool(
+ 'echo',
+ {
+ description: 'Echoes the input text back as a text content block.',
+ inputSchema: z.object({ text: z.string() })
+ },
+ ({ text }) => ({ content: [{ type: 'text', text }] })
+);
+
+await server.connect(new StdioServerTransport());
+process.stderr.write('[dual-era-stdio-server] ready\n');

test/e2e/helpers/index.ts

@@ -15,30 +15,93 @@ import { PassThrough } from 'node:stream';
 
 import type { Client } from '@modelcontextprotocol/client';
 import { SSEClientTransport, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
-import type { EventStore, JSONRPCMessage, McpServer, Server } from '@modelcontextprotocol/server';
-import { InMemoryTransport, ReadBuffer, serializeMessage, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY } from '@modelcontextprotocol/core';
+import type {
+ CreateMcpHandlerOptions,
+ EventStore,
+ Implementation,
+ JSONRPCMessage,
+ McpRequestContext,
+ McpServer,
+ Server,
+ Transport as SdkTransport
+} from '@modelcontextprotocol/server';
+import {
+ createMcpHandler,
+ InMemoryTransport,
+ ReadBuffer,
+ serializeMessage,
+ WebStandardStreamableHTTPServerTransport
+} from '@modelcontextprotocol/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 
-import type { Transport } from '../types.js';
+import type { SpecVersion, Transport } from '../types.js';
 import { startLegacySseHost } from './sse-host.js';
 import type { SnifferOptions } from './wire-sniffer.js';
 import { sniffTransport } from './wire-sniffer.js';
 
 export type ServerFactory = () => McpServer | Server;
 
+/**
+ * A factory that optionally consumes the createMcpHandler per-request context.
+ * The context is only supplied on the entry arms (where the entry constructs a
+ * fresh instance per request); on every other arm the factory is called with no
+ * arguments, so declare the parameter optional.
+ */
+export type EntryServerFactory = (ctx?: McpRequestContext) => McpServer | Server;
+
+/** One HTTP exchange recorded by the entry arms (see {@linkcode Wired.httpLog}). */
+export interface RecordedHttpExchange {
+ /** HTTP request method (GET/POST/DELETE). */
+ method: string;
+ /** The request body text, when one was sent as a string. */
+ requestBody?: string;
+ /** HTTP response status. */
+ status: number;
+ /** Response content-type header (empty string when absent). */
+ contentType: string;
+ /** An unread clone of the HTTP response, for byte-level assertions (`await exchange.response.text()`). */
+ response: Response;
+}
+
 export interface Wired extends AsyncDisposable {
  readonly fetch?: (url: URL | string, init?: RequestInit) => Promise<Response>;
  readonly url?: URL;
+ /**
+ * Every HTTP exchange the wired client performed, in order, including the
+ * connect-time negotiation. Recorded by the createMcpHandler entry arms
+ * only — scenarios on those arms use it to assert raw wire facts (request
+ * bodies, response status/content-type/bytes) that the typed client API
+ * does not expose.
+ */
+ readonly httpLog?: readonly RecordedHttpExchange[];
 }
 
 /**
- * The fourth argument controls the wire-format sniffer (see wire-sniffer.ts):
- * every message the client sends or receives is validated against the SDK's
- * spec-anchored Zod schemas. Tests that intentionally use vendor-extension
- * methods pass `{ allowCustomMethods: true }`; tests that deliberately put
- * malformed MCP on the wire pass `{ strictValidation: false }`.
+ * The fourth argument's sniffer options control the wire-format sniffer (see
+ * wire-sniffer.ts): every message the client sends or receives is validated
+ * against the SDK's spec-anchored Zod schemas. Tests that intentionally use
+ * vendor-extension methods pass `{ allowCustomMethods: true }`; tests that
+ * deliberately put malformed MCP on the wire pass `{ strictValidation: false }`.
+ * `entry` overrides the hosting options of the createMcpHandler entry arms
+ * (ignored by every other transport).
  */
-export async function wire(transport: Transport, makeServer: ServerFactory, client: Client, sniff: SnifferOptions = {}): Promise<Wired> {
+export interface WireOptions extends SnifferOptions {
+ /**
+ * createMcpHandler hosting overrides for the entry arms. Defaults:
+ * `{ legacy: 'stateless' }` on entryStateless (the canonical slot value) and
+ * modern-only strict (no legacy slot) on entryModern. `onerror` and
+ * `responseMode` pass through unchanged.
+ */
+ entry?: CreateMcpHandlerOptions;
+}
+
+export async function wire(
+ transport: Transport,
+ makeServer: ServerFactory | EntryServerFactory,
+ client: Client,
+ sniff: WireOptions = {}
+): Promise<Wired> {
  switch (transport) {
  case 'inMemory': {
  const server = makeServer();
@@ -67,6 +130,47 @@ export async function wire(transport: Transport, makeServer: ServerFactory, clie
  [Symbol.asyncDispose]: () => Promise.all([client.close(), handle.close()]).then(() => {})
  };
  }
+ case 'entryStateless':
+ case 'entryModern': {
+ // The dual-era HTTP entry (`createMcpHandler`) hosted in process via an
+ // injected fetch, exactly like the other HTTP arms. The scenario factory
+ // backs the entry directly (the entry calls it once per request with its
+ // per-request context). `entryStateless` serves the scenario's plain
+ // client through the entry's `legacy: 'stateless'` slot; `entryModern`
+ // keeps the endpoint modern-only strict and connects the client on the
+ // 2026-07-28 revision (pin-mode negotiation + the per-request envelope
+ // stop-gap). Every HTTP exchange is recorded on `httpLog`.
+ const handler = createMcpHandler(
+ makeServer,
+ transport === 'entryStateless' ? { legacy: 'stateless', ...sniff.entry } : { ...sniff.entry }
+ );
+ const url = new URL('http://in-process/mcp');
+ const httpLog: RecordedHttpExchange[] = [];
+ const fetch = async (u: URL | string, init?: RequestInit) => {
+ const request = new Request(u, init);
+ const response = await handler.fetch(request);
+ httpLog.push({
+ method: request.method.toUpperCase(),
+ ...(typeof init?.body === 'string' && { requestBody: init.body }),
+ status: response.status,
+ contentType: response.headers.get('content-type') ?? '',
+ response: response.clone()
+ });
+ return response;
+ };
+ let clientTx = new StreamableHTTPClientTransport(url, { fetch });
+ if (transport === 'entryModern') {
+ pinModernNegotiation(client);
+ clientTx = attachModernEnvelope(clientTx);
+ }
+ await client.connect(sniffTransport(clientTx, 'client', sniff));
+ return {
+ fetch,
+ url,
+ httpLog,
+ [Symbol.asyncDispose]: () => Promise.all([client.close(), handler.close()]).then(() => {})
+ };
+ }
  case 'sse': {
  // The legacy SSE transport needs a real socket: the factory's server is hosted on the
  // shipped SSEServerTransport (@modelcontextprotocol/server-legacy/sse) behind a loopback
@@ -212,6 +316,78 @@ export function hostStateless(makeServer: ServerFactory): { handleRequest: HttpH
  };
 }
 
+// ───────────────────────────────────────────────────────────────────────────────
+// createMcpHandler entry arms (entryStateless / entryModern) — client-side shims
+// ───────────────────────────────────────────────────────────────────────────────
+
+/** The protocol revision the entryModern arm negotiates and claims per request. */
+const MODERN_REVISION: SpecVersion = '2026-07-28';
+
+/**
+ * The per-request `_meta` envelope of a 2026-07-28 request, for scenario bodies
+ * that put raw HTTP requests on the wire (via `wired.fetch`) rather than going
+ * through the wired client. Typed calls through the wired client never need
+ * this — the entryModern arm attaches the envelope itself (see
+ * {@linkcode attachModernEnvelope}).
+ */
+export function modernEnvelopeMeta(clientInfo?: Implementation): Record<string, unknown> {
+ return {
+ [PROTOCOL_VERSION_META_KEY]: MODERN_REVISION,
+ [CLIENT_INFO_META_KEY]: clientInfo ?? { name: 'e2e-entry-client', version: '1.0.0' },
+ [CLIENT_CAPABILITIES_META_KEY]: {}
+ };
+}
+
+/**
+ * Put the (already constructed) scenario client into pinned 2026-07-28
+ * negotiation. Version negotiation is a constructor-only option and the
+ * scenario corpus constructs era-agnostic clients, so the entryModern arm flips
+ * the option on the instance before `connect()` — a harness stop-gap, not a
+ * public API. Clients that already opted into a negotiation mode are left
+ * untouched (their cells deliberately exercise that mode).
+ */
+function pinModernNegotiation(client: Client): void {
+ const internals = client as unknown as { _versionNegotiation?: { mode?: unknown } };
+ internals._versionNegotiation ??= { mode: { pin: MODERN_REVISION } };
+}
+
+/**
+ * The per-request `_meta` envelope stop-gap for the entryModern arm: the
+ * negotiating client only attaches the envelope to its `server/discover` probe
+ * today (automatic per-request emission is a client-side follow-up), so the
+ * harness re-attaches the same envelope to every later request and notification
+ * the scenario's typed calls put on the wire. The envelope is captured from the
+ * probe itself, so it always matches what the client actually claimed; messages
+ * that already carry a protocol-version claim (the probe, or a scenario's
+ * explicitly enveloped request) pass through untouched.
+ *
+ * Applied beneath the wire sniffer and `tapWire`, so recorded traffic shows the
+ * messages exactly as the scenario sent them while the wire carries the
+ * envelope the entry requires.
+ */
+function attachModernEnvelope<T extends SdkTransport>(transport: T): T {
+ let envelope: Record<string, unknown> | undefined;
+ const origSend = transport.send.bind(transport);
+ transport.send = async (message, opts) => {
+ let outbound = message;
+ if ('method' in message) {
+ const params = (message.params ?? {}) as { _meta?: Record<string, unknown> };
+ const meta = params._meta;
+ if (meta?.[PROTOCOL_VERSION_META_KEY] !== undefined) {
+ envelope ??= {
+ [PROTOCOL_VERSION_META_KEY]: meta[PROTOCOL_VERSION_META_KEY],
+ [CLIENT_INFO_META_KEY]: meta[CLIENT_INFO_META_KEY],
+ [CLIENT_CAPABILITIES_META_KEY]: meta[CLIENT_CAPABILITIES_META_KEY]
+ };
+ } else if (envelope !== undefined) {
+ outbound = { ...message, params: { ...params, _meta: { ...envelope, ...meta } } };
+ }
+ }
+ return origSend(outbound, opts);
+ };
+ return transport;
+}
+
 // ───────────────────────────────────────────────────────────────────────────────
 // In-process stdio client — TEST-ONLY
 //

test/e2e/helpers/verifies.ts

@@ -18,11 +18,23 @@
 import { describe, test } from 'vitest';
 
 import { REQUIREMENTS } from '../requirements.js';
-import type { TestArgs } from '../types.js';
-import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS } from '../types.js';
+import type { Requirement, SpecVersion, TestArgs, Transport } from '../types.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from '../types.js';
 
 type TestBody = (args: TestArgs) => Promise<void>;
 
+/** Whether a requirement's `entryExclusions` keep the given entry arm out of its cells. */
+function excludedFromEntryArm(req: Requirement, transport: Transport): boolean {
+ if (!(ENTRY_TRANSPORTS as readonly Transport[]).includes(transport)) return false;
+ return (req.entryExclusions ?? []).some(x => x.arm === undefined || x.arm === transport);
+}
+
+/** Whether a transport arm serves the given spec version (era-fixed arms serve exactly one). */
+function transportServesVersion(transport: Transport, version: SpecVersion): boolean {
+ const versions = TRANSPORT_SPEC_VERSIONS[transport];
+ return versions === undefined || versions.includes(version);
+}
+
 export function verifies(id: string | readonly string[], fn: TestBody, opts?: { title?: string }): void {
  const ids = Array.isArray(id) ? id : [id];
  for (const rid of ids) registerOne(rid, fn, opts);
@@ -33,13 +45,13 @@ function registerOne(id: string, fn: TestBody, opts?: { title?: string }): void
  if (!req) throw new Error(`verifies('${id}'): unknown requirement id`);
  if (req.deferred) throw new Error(`verifies('${id}'): requirement is deferred — drop the deferral or the test`);
 
- const transports = req.transports ?? ALL_TRANSPORTS;
+ const transports = (req.transports ?? ALL_TRANSPORTS).filter(t => !excludedFromEntryArm(req, t));
  const versions = ALL_SPEC_VERSIONS.filter(
  v =>
  (req.addedInSpecVersion === undefined || v >= req.addedInSpecVersion) &&
  (req.removedInSpecVersion === undefined || v < req.removedInSpecVersion)
  );
- const cells = versions.flatMap(v => transports.map(t => [t, v] as const));
+ const cells = versions.flatMap(v => transports.filter(t => transportServesVersion(t, v)).map(t => [t, v] as const));
 
  describe.each(cells)(`${id} [%s %s]`, (transport, protocolVersion) => {
  const kf = req.knownFailures?.find(

test/e2e/CLAUDE.md

@@ -58,6 +58,26 @@ note: 'stateless hosting has no server→client back-channel'
 `addedInSpecVersion` / `removedInSpecVersion` bound the spec versions a requirement applies to. A behavior changed by a spec release gets a sibling entry: the new entry lists every retired id it replaces in `supersedes` (an array, requires `addedInSpecVersion`), and each retired
 entry points back via `supersededBy` (requires `removedInSpecVersion`). A coverage gate enforces that the links resolve and are exactly symmetric.
 
+## The createMcpHandler entry arms (entryStateless / entryModern)
+
+Two transport arms host the dual-era HTTP entry (`createMcpHandler`) in process via an injected fetch, exactly like the other HTTP arms. They are era-fixed (`TRANSPORT_SPEC_VERSIONS`), so each registers cells on exactly one spec-version axis:
+
+- `entryStateless` — the entry with the `legacy: 'stateless'` slot; the scenario's plain client is served per request through the slot. Cells run on the 2025-11-25 axis only.
+- `entryModern` — the entry modern-only strict (no legacy slot); the scenario's client is put into pinned 2026-07-28 negotiation by the arm and the per-request `_meta` envelope is attached to every outgoing request/notification by the arm (a harness stop-gap until the client
+ emits it itself). Cells run on the 2026-07-28 axis only.
+
+Both arms are part of the default transport list, so unrestricted requirements run through the entry automatically. When a requirement cannot run on an entry arm, annotate it with a machine-readable reason instead of bending the test:
+
+```ts
+entryExclusions: [{ arm: 'entryModern', reason: 'method-not-in-modern-registry' /* optional note */ }];
+```
+
+Omitting `arm` excludes both arms. The reasons (`EntryExclusionReason` in types.ts) are the acceptance checklist for re-admitting cells when the corresponding entry feature lands; a coverage gate rejects annotations that would never have an effect. Requirement families that the
+per-request entry structurally cannot serve at all (server→client requests, sessions/resumability, standalone GET streams, subscriptions) are already expressed through their `transports` restrictions and need no annotation.
+
+Arm-specific helpers: `wire()`'s fourth argument also accepts `entry` (createMcpHandler hosting overrides — e.g. a `responseMode` or a bring-your-own `legacy` slot value), the returned `Wired.httpLog` records every HTTP exchange (request body, status, content-type, a readable
+response clone) for raw wire assertions, factories may accept the optional per-request context (`EntryServerFactory`), and `modernEnvelopeMeta()` builds the envelope for bodies that POST raw 2026-era requests through `wired.fetch`.
+
 ## Running
 
 From the repo root (the suite is the `@modelcontextprotocol/test-e2e` workspace package):

test/e2e/coverage.test.ts

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { expect, test } from 'vitest';
 
 import { REQUIREMENTS } from './requirements.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from './types.js';
 
 const E2E_DIR = path.dirname(fileURLToPath(import.meta.url));
 
@@ -88,6 +89,34 @@ test('every transport-restricted requirement explains why in note', () => {
  expect(missing).toEqual([]);
 });
 
+test('every entryExclusions annotation targets an entry arm the requirement would otherwise run on', () => {
+ const bad: string[] = [];
+ for (const [id, r] of Object.entries(REQUIREMENTS)) {
+ for (const exclusion of r.entryExclusions ?? []) {
+ const arms = exclusion.arm === undefined ? ENTRY_TRANSPORTS : [exclusion.arm];
+ for (const arm of arms) {
+ const transports = r.transports ?? ALL_TRANSPORTS;
+ if (!transports.includes(arm)) {
+ bad.push(`${id}: entryExclusions targets '${arm}', which the requirement's transports never include`);
+ continue;
+ }
+ const versions = ALL_SPEC_VERSIONS.filter(
+ v =>
+ (r.addedInSpecVersion === undefined || v >= r.addedInSpecVersion) &&
+ (r.removedInSpecVersion === undefined || v < r.removedInSpecVersion) &&
+ (TRANSPORT_SPEC_VERSIONS[arm]?.includes(v) ?? true)
+ );
+ if (versions.length === 0) {
+ bad.push(
+ `${id}: entryExclusions targets '${arm}', which registers no cells within the requirement's spec-version bounds`
+ );
+ }
+ }
+ }
+ }
+ expect(bad).toEqual([]);
+});
+
 test('supersedes/supersededBy links are symmetric and resolve', () => {
  const bad: string[] = [];
  for (const [id, req] of Object.entries(REQUIREMENTS)) {

test/e2e/fixtures/dual-era-stdio-server.ts

@@ -0,0 +1,29 @@
+/**
+ * Runnable dual-era stdio MCP server fixture for the dual-era stdio e2e cells.
+ *
+ * `eraSupport: 'dual-era'` is the single declared act on an otherwise ordinary
+ * hand-constructed McpServer connected to the unchanged StdioServerTransport.
+ * Spawned as a real child process (via tsx) by
+ * test/e2e/scenarios/stdio-dual-era.test.ts; exits when its stdin reaches EOF.
+ */
+
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { z } from 'zod/v4';
+
+const server = new McpServer(
+ { name: 'dual-era-stdio-e2e-fixture', version: '1.0.0' },
+ { capabilities: { tools: {} }, eraSupport: 'dual-era' }
+);
+
+server.registerTool(
+ 'echo',
+ {
+ description: 'Echoes the input text back as a text content block.',
+ inputSchema: z.object({ text: z.string() })
+ },
+ ({ text }) => ({ content: [{ type: 'text', text }] })
+);
+
+await server.connect(new StdioServerTransport());
+process.stderr.write('[dual-era-stdio-server] ready\n');

test/e2e/helpers/index.ts

@@ -15,30 +15,93 @@ import { PassThrough } from 'node:stream';
 
 import type { Client } from '@modelcontextprotocol/client';
 import { SSEClientTransport, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
-import type { EventStore, JSONRPCMessage, McpServer, Server } from '@modelcontextprotocol/server';
-import { InMemoryTransport, ReadBuffer, serializeMessage, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY } from '@modelcontextprotocol/core';
+import type {
+ CreateMcpHandlerOptions,
+ EventStore,
+ Implementation,
+ JSONRPCMessage,
+ McpRequestContext,
+ McpServer,
+ Server,
+ Transport as SdkTransport
+} from '@modelcontextprotocol/server';
+import {
+ createMcpHandler,
+ InMemoryTransport,
+ ReadBuffer,
+ serializeMessage,
+ WebStandardStreamableHTTPServerTransport
+} from '@modelcontextprotocol/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 
-import type { Transport } from '../types.js';
+import type { SpecVersion, Transport } from '../types.js';
 import { startLegacySseHost } from './sse-host.js';
 import type { SnifferOptions } from './wire-sniffer.js';
 import { sniffTransport } from './wire-sniffer.js';
 
 export type ServerFactory = () => McpServer | Server;
 
+/**
+ * A factory that optionally consumes the createMcpHandler per-request context.
+ * The context is only supplied on the entry arms (where the entry constructs a
+ * fresh instance per request); on every other arm the factory is called with no
+ * arguments, so declare the parameter optional.
+ */
+export type EntryServerFactory = (ctx?: McpRequestContext) => McpServer | Server;
+
+/** One HTTP exchange recorded by the entry arms (see {@linkcode Wired.httpLog}). */
+export interface RecordedHttpExchange {
+ /** HTTP request method (GET/POST/DELETE). */
+ method: string;
+ /** The request body text, when one was sent as a string. */
+ requestBody?: string;
+ /** HTTP response status. */
+ status: number;
+ /** Response content-type header (empty string when absent). */
+ contentType: string;
+ /** An unread clone of the HTTP response, for byte-level assertions (`await exchange.response.text()`). */
+ response: Response;
+}
+
 export interface Wired extends AsyncDisposable {
  readonly fetch?: (url: URL | string, init?: RequestInit) => Promise<Response>;
  readonly url?: URL;
+ /**
+ * Every HTTP exchange the wired client performed, in order, including the
+ * connect-time negotiation. Recorded by the createMcpHandler entry arms
+ * only — scenarios on those arms use it to assert raw wire facts (request
+ * bodies, response status/content-type/bytes) that the typed client API
+ * does not expose.
+ */
+ readonly httpLog?: readonly RecordedHttpExchange[];
 }
 
 /**
- * The fourth argument controls the wire-format sniffer (see wire-sniffer.ts):
- * every message the client sends or receives is validated against the SDK's
- * spec-anchored Zod schemas. Tests that intentionally use vendor-extension
- * methods pass `{ allowCustomMethods: true }`; tests that deliberately put
- * malformed MCP on the wire pass `{ strictValidation: false }`.
+ * The fourth argument's sniffer options control the wire-format sniffer (see
+ * wire-sniffer.ts): every message the client sends or receives is validated
+ * against the SDK's spec-anchored Zod schemas. Tests that intentionally use
+ * vendor-extension methods pass `{ allowCustomMethods: true }`; tests that
+ * deliberately put malformed MCP on the wire pass `{ strictValidation: false }`.
+ * `entry` overrides the hosting options of the createMcpHandler entry arms
+ * (ignored by every other transport).
  */
-export async function wire(transport: Transport, makeServer: ServerFactory, client: Client, sniff: SnifferOptions = {}): Promise<Wired> {
+export interface WireOptions extends SnifferOptions {
+ /**
+ * createMcpHandler hosting overrides for the entry arms. Defaults:
+ * `{ legacy: 'stateless' }` on entryStateless (the canonical slot value) and
+ * modern-only strict (no legacy slot) on entryModern. `onerror` and
+ * `responseMode` pass through unchanged.
+ */
+ entry?: CreateMcpHandlerOptions;
+}
+
+export async function wire(
+ transport: Transport,
+ makeServer: ServerFactory | EntryServerFactory,
+ client: Client,
+ sniff: WireOptions = {}
+): Promise<Wired> {
  switch (transport) {
  case 'inMemory': {
  const server = makeServer();
@@ -67,6 +130,47 @@ export async function wire(transport: Transport, makeServer: ServerFactory, clie
  [Symbol.asyncDispose]: () => Promise.all([client.close(), handle.close()]).then(() => {})
  };
  }
+ case 'entryStateless':
+ case 'entryModern': {
+ // The dual-era HTTP entry (`createMcpHandler`) hosted in process via an
+ // injected fetch, exactly like the other HTTP arms. The scenario factory
+ // backs the entry directly (the entry calls it once per request with its
+ // per-request context). `entryStateless` serves the scenario's plain
+ // client through the entry's `legacy: 'stateless'` slot; `entryModern`
+ // keeps the endpoint modern-only strict and connects the client on the
+ // 2026-07-28 revision (pin-mode negotiation + the per-request envelope
+ // stop-gap). Every HTTP exchange is recorded on `httpLog`.
+ const handler = createMcpHandler(
+ makeServer,
+ transport === 'entryStateless' ? { legacy: 'stateless', ...sniff.entry } : { ...sniff.entry }
+ );
+ const url = new URL('http://in-process/mcp');
+ const httpLog: RecordedHttpExchange[] = [];
+ const fetch = async (u: URL | string, init?: RequestInit) => {
+ const request = new Request(u, init);
+ const response = await handler.fetch(request);
+ httpLog.push({
+ method: request.method.toUpperCase(),
+ ...(typeof init?.body === 'string' && { requestBody: init.body }),
+ status: response.status,
+ contentType: response.headers.get('content-type') ?? '',
+ response: response.clone()
+ });
+ return response;
+ };
+ let clientTx = new StreamableHTTPClientTransport(url, { fetch });
+ if (transport === 'entryModern') {
+ pinModernNegotiation(client);
+ clientTx = attachModernEnvelope(clientTx);
+ }
+ await client.connect(sniffTransport(clientTx, 'client', sniff));
+ return {
+ fetch,
+ url,
+ httpLog,
+ [Symbol.asyncDispose]: () => Promise.all([client.close(), handler.close()]).then(() => {})
+ };
+ }
  case 'sse': {
  // The legacy SSE transport needs a real socket: the factory's server is hosted on the
  // shipped SSEServerTransport (@modelcontextprotocol/server-legacy/sse) behind a loopback
@@ -212,6 +316,78 @@ export function hostStateless(makeServer: ServerFactory): { handleRequest: HttpH
  };
 }
 
+// ───────────────────────────────────────────────────────────────────────────────
+// createMcpHandler entry arms (entryStateless / entryModern) — client-side shims
+// ───────────────────────────────────────────────────────────────────────────────
+
+/** The protocol revision the entryModern arm negotiates and claims per request. */
+const MODERN_REVISION: SpecVersion = '2026-07-28';
+
+/**
+ * The per-request `_meta` envelope of a 2026-07-28 request, for scenario bodies
+ * that put raw HTTP requests on the wire (via `wired.fetch`) rather than going
+ * through the wired client. Typed calls through the wired client never need
+ * this — the entryModern arm attaches the envelope itself (see
+ * {@linkcode attachModernEnvelope}).
+ */
+export function modernEnvelopeMeta(clientInfo?: Implementation): Record<string, unknown> {
+ return {
+ [PROTOCOL_VERSION_META_KEY]: MODERN_REVISION,
+ [CLIENT_INFO_META_KEY]: clientInfo ?? { name: 'e2e-entry-client', version: '1.0.0' },
+ [CLIENT_CAPABILITIES_META_KEY]: {}
+ };
+}
+
+/**
+ * Put the (already constructed) scenario client into pinned 2026-07-28
+ * negotiation. Version negotiation is a constructor-only option and the
+ * scenario corpus constructs era-agnostic clients, so the entryModern arm flips
+ * the option on the instance before `connect()` — a harness stop-gap, not a
+ * public API. Clients that already opted into a negotiation mode are left
+ * untouched (their cells deliberately exercise that mode).
+ */
+function pinModernNegotiation(client: Client): void {
+ const internals = client as unknown as { _versionNegotiation?: { mode?: unknown } };
+ internals._versionNegotiation ??= { mode: { pin: MODERN_REVISION } };
+}
+
+/**
+ * The per-request `_meta` envelope stop-gap for the entryModern arm: the
+ * negotiating client only attaches the envelope to its `server/discover` probe
+ * today (automatic per-request emission is a client-side follow-up), so the
+ * harness re-attaches the same envelope to every later request and notification
+ * the scenario's typed calls put on the wire. The envelope is captured from the
+ * probe itself, so it always matches what the client actually claimed; messages
+ * that already carry a protocol-version claim (the probe, or a scenario's
+ * explicitly enveloped request) pass through untouched.
+ *
+ * Applied beneath the wire sniffer and `tapWire`, so recorded traffic shows the
+ * messages exactly as the scenario sent them while the wire carries the
+ * envelope the entry requires.
+ */
+function attachModernEnvelope<T extends SdkTransport>(transport: T): T {
+ let envelope: Record<string, unknown> | undefined;
+ const origSend = transport.send.bind(transport);
+ transport.send = async (message, opts) => {
+ let outbound = message;
+ if ('method' in message) {
+ const params = (message.params ?? {}) as { _meta?: Record<string, unknown> };
+ const meta = params._meta;
+ if (meta?.[PROTOCOL_VERSION_META_KEY] !== undefined) {
+ envelope ??= {
+ [PROTOCOL_VERSION_META_KEY]: meta[PROTOCOL_VERSION_META_KEY],
+ [CLIENT_INFO_META_KEY]: meta[CLIENT_INFO_META_KEY],
+ [CLIENT_CAPABILITIES_META_KEY]: meta[CLIENT_CAPABILITIES_META_KEY]
+ };
+ } else if (envelope !== undefined) {
+ outbound = { ...message, params: { ...params, _meta: { ...envelope, ...meta } } };
+ }
+ }
+ return origSend(outbound, opts);
+ };
+ return transport;
+}
+
 // ───────────────────────────────────────────────────────────────────────────────
 // In-process stdio client — TEST-ONLY
 //

test/e2e/helpers/verifies.ts

@@ -18,11 +18,23 @@
 import { describe, test } from 'vitest';
 
 import { REQUIREMENTS } from '../requirements.js';
-import type { TestArgs } from '../types.js';
-import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS } from '../types.js';
+import type { Requirement, SpecVersion, TestArgs, Transport } from '../types.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from '../types.js';
 
 type TestBody = (args: TestArgs) => Promise<void>;
 
+/** Whether a requirement's `entryExclusions` keep the given entry arm out of its cells. */
+function excludedFromEntryArm(req: Requirement, transport: Transport): boolean {
+ if (!(ENTRY_TRANSPORTS as readonly Transport[]).includes(transport)) return false;
+ return (req.entryExclusions ?? []).some(x => x.arm === undefined || x.arm === transport);
+}
+
+/** Whether a transport arm serves the given spec version (era-fixed arms serve exactly one). */
+function transportServesVersion(transport: Transport, version: SpecVersion): boolean {
+ const versions = TRANSPORT_SPEC_VERSIONS[transport];
+ return versions === undefined || versions.includes(version);
+}
+
 export function verifies(id: string | readonly string[], fn: TestBody, opts?: { title?: string }): void {
  const ids = Array.isArray(id) ? id : [id];
  for (const rid of ids) registerOne(rid, fn, opts);
@@ -33,13 +45,13 @@ function registerOne(id: string, fn: TestBody, opts?: { title?: string }): void
  if (!req) throw new Error(`verifies('${id}'): unknown requirement id`);
  if (req.deferred) throw new Error(`verifies('${id}'): requirement is deferred — drop the deferral or the test`);
 
- const transports = req.transports ?? ALL_TRANSPORTS;
+ const transports = (req.transports ?? ALL_TRANSPORTS).filter(t => !excludedFromEntryArm(req, t));
  const versions = ALL_SPEC_VERSIONS.filter(
  v =>
  (req.addedInSpecVersion === undefined || v >= req.addedInSpecVersion) &&
  (req.removedInSpecVersion === undefined || v < req.removedInSpecVersion)
  );
- const cells = versions.flatMap(v => transports.map(t => [t, v] as const));
+ const cells = versions.flatMap(v => transports.filter(t => transportServesVersion(t, v)).map(t => [t, v] as const));
 
  describe.each(cells)(`${id} [%s %s]`, (transport, protocolVersion) => {
  const kf = req.knownFailures?.find(

test/e2e/CLAUDE.md

@@ -58,6 +58,26 @@ note: 'stateless hosting has no server→client back-channel'
 `addedInSpecVersion` / `removedInSpecVersion` bound the spec versions a requirement applies to. A behavior changed by a spec release gets a sibling entry: the new entry lists every retired id it replaces in `supersedes` (an array, requires `addedInSpecVersion`), and each retired
 entry points back via `supersededBy` (requires `removedInSpecVersion`). A coverage gate enforces that the links resolve and are exactly symmetric.
 
+## The createMcpHandler entry arms (entryStateless / entryModern)
+
+Two transport arms host the dual-era HTTP entry (`createMcpHandler`) in process via an injected fetch, exactly like the other HTTP arms. They are era-fixed (`TRANSPORT_SPEC_VERSIONS`), so each registers cells on exactly one spec-version axis:
+
+- `entryStateless` — the entry with the `legacy: 'stateless'` slot; the scenario's plain client is served per request through the slot. Cells run on the 2025-11-25 axis only.
+- `entryModern` — the entry modern-only strict (no legacy slot); the scenario's client is put into pinned 2026-07-28 negotiation by the arm and the per-request `_meta` envelope is attached to every outgoing request/notification by the arm (a harness stop-gap until the client
+ emits it itself). Cells run on the 2026-07-28 axis only.
+
+Both arms are part of the default transport list, so unrestricted requirements run through the entry automatically. When a requirement cannot run on an entry arm, annotate it with a machine-readable reason instead of bending the test:
+
+```ts
+entryExclusions: [{ arm: 'entryModern', reason: 'method-not-in-modern-registry' /* optional note */ }];
+```
+
+Omitting `arm` excludes both arms. The reasons (`EntryExclusionReason` in types.ts) are the acceptance checklist for re-admitting cells when the corresponding entry feature lands; a coverage gate rejects annotations that would never have an effect. Requirement families that the
+per-request entry structurally cannot serve at all (server→client requests, sessions/resumability, standalone GET streams, subscriptions) are already expressed through their `transports` restrictions and need no annotation.
+
+Arm-specific helpers: `wire()`'s fourth argument also accepts `entry` (createMcpHandler hosting overrides — e.g. a `responseMode` or a bring-your-own `legacy` slot value), the returned `Wired.httpLog` records every HTTP exchange (request body, status, content-type, a readable
+response clone) for raw wire assertions, factories may accept the optional per-request context (`EntryServerFactory`), and `modernEnvelopeMeta()` builds the envelope for bodies that POST raw 2026-era requests through `wired.fetch`.
+
 ## Running
 
 From the repo root (the suite is the `@modelcontextprotocol/test-e2e` workspace package):

test/e2e/coverage.test.ts

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { expect, test } from 'vitest';
 
 import { REQUIREMENTS } from './requirements.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from './types.js';
 
 const E2E_DIR = path.dirname(fileURLToPath(import.meta.url));
 
@@ -88,6 +89,34 @@ test('every transport-restricted requirement explains why in note', () => {
  expect(missing).toEqual([]);
 });
 
+test('every entryExclusions annotation targets an entry arm the requirement would otherwise run on', () => {
+ const bad: string[] = [];
+ for (const [id, r] of Object.entries(REQUIREMENTS)) {
+ for (const exclusion of r.entryExclusions ?? []) {
+ const arms = exclusion.arm === undefined ? ENTRY_TRANSPORTS : [exclusion.arm];
+ for (const arm of arms) {
+ const transports = r.transports ?? ALL_TRANSPORTS;
+ if (!transports.includes(arm)) {
+ bad.push(`${id}: entryExclusions targets '${arm}', which the requirement's transports never include`);
+ continue;
+ }
+ const versions = ALL_SPEC_VERSIONS.filter(
+ v =>
+ (r.addedInSpecVersion === undefined || v >= r.addedInSpecVersion) &&
+ (r.removedInSpecVersion === undefined || v < r.removedInSpecVersion) &&
+ (TRANSPORT_SPEC_VERSIONS[arm]?.includes(v) ?? true)
+ );
+ if (versions.length === 0) {
+ bad.push(
+ `${id}: entryExclusions targets '${arm}', which registers no cells within the requirement's spec-version bounds`
+ );
+ }
+ }
+ }
+ }
+ expect(bad).toEqual([]);
+});
+
 test('supersedes/supersededBy links are symmetric and resolve', () => {
  const bad: string[] = [];
  for (const [id, req] of Object.entries(REQUIREMENTS)) {

test/e2e/fixtures/dual-era-stdio-server.ts

@@ -0,0 +1,29 @@
+/**
+ * Runnable dual-era stdio MCP server fixture for the dual-era stdio e2e cells.
+ *
+ * `eraSupport: 'dual-era'` is the single declared act on an otherwise ordinary
+ * hand-constructed McpServer connected to the unchanged StdioServerTransport.
+ * Spawned as a real child process (via tsx) by
+ * test/e2e/scenarios/stdio-dual-era.test.ts; exits when its stdin reaches EOF.
+ */
+
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { z } from 'zod/v4';
+
+const server = new McpServer(
+ { name: 'dual-era-stdio-e2e-fixture', version: '1.0.0' },
+ { capabilities: { tools: {} }, eraSupport: 'dual-era' }
+);
+
+server.registerTool(
+ 'echo',
+ {
+ description: 'Echoes the input text back as a text content block.',
+ inputSchema: z.object({ text: z.string() })
+ },
+ ({ text }) => ({ content: [{ type: 'text', text }] })
+);
+
+await server.connect(new StdioServerTransport());
+process.stderr.write('[dual-era-stdio-server] ready\n');

test/e2e/helpers/index.ts

@@ -15,30 +15,93 @@ import { PassThrough } from 'node:stream';
 
 import type { Client } from '@modelcontextprotocol/client';
 import { SSEClientTransport, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
-import type { EventStore, JSONRPCMessage, McpServer, Server } from '@modelcontextprotocol/server';
-import { InMemoryTransport, ReadBuffer, serializeMessage, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY } from '@modelcontextprotocol/core';
+import type {
+ CreateMcpHandlerOptions,
+ EventStore,
+ Implementation,
+ JSONRPCMessage,
+ McpRequestContext,
+ McpServer,
+ Server,
+ Transport as SdkTransport
+} from '@modelcontextprotocol/server';
+import {
+ createMcpHandler,
+ InMemoryTransport,
+ ReadBuffer,
+ serializeMessage,
+ WebStandardStreamableHTTPServerTransport
+} from '@modelcontextprotocol/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 
-import type { Transport } from '../types.js';
+import type { SpecVersion, Transport } from '../types.js';
 import { startLegacySseHost } from './sse-host.js';
 import type { SnifferOptions } from './wire-sniffer.js';
 import { sniffTransport } from './wire-sniffer.js';
 
 export type ServerFactory = () => McpServer | Server;
 
+/**
+ * A factory that optionally consumes the createMcpHandler per-request context.
+ * The context is only supplied on the entry arms (where the entry constructs a
+ * fresh instance per request); on every other arm the factory is called with no
+ * arguments, so declare the parameter optional.
+ */
+export type EntryServerFactory = (ctx?: McpRequestContext) => McpServer | Server;
+
+/** One HTTP exchange recorded by the entry arms (see {@linkcode Wired.httpLog}). */
+export interface RecordedHttpExchange {
+ /** HTTP request method (GET/POST/DELETE). */
+ method: string;
+ /** The request body text, when one was sent as a string. */
+ requestBody?: string;
+ /** HTTP response status. */
+ status: number;
+ /** Response content-type header (empty string when absent). */
+ contentType: string;
+ /** An unread clone of the HTTP response, for byte-level assertions (`await exchange.response.text()`). */
+ response: Response;
+}
+
 export interface Wired extends AsyncDisposable {
  readonly fetch?: (url: URL | string, init?: RequestInit) => Promise<Response>;
  readonly url?: URL;
+ /**
+ * Every HTTP exchange the wired client performed, in order, including the
+ * connect-time negotiation. Recorded by the createMcpHandler entry arms
+ * only — scenarios on those arms use it to assert raw wire facts (request
+ * bodies, response status/content-type/bytes) that the typed client API
+ * does not expose.
+ */
+ readonly httpLog?: readonly RecordedHttpExchange[];
 }
 
 /**
- * The fourth argument controls the wire-format sniffer (see wire-sniffer.ts):
- * every message the client sends or receives is validated against the SDK's
- * spec-anchored Zod schemas. Tests that intentionally use vendor-extension
- * methods pass `{ allowCustomMethods: true }`; tests that deliberately put
- * malformed MCP on the wire pass `{ strictValidation: false }`.
+ * The fourth argument's sniffer options control the wire-format sniffer (see
+ * wire-sniffer.ts): every message the client sends or receives is validated
+ * against the SDK's spec-anchored Zod schemas. Tests that intentionally use
+ * vendor-extension methods pass `{ allowCustomMethods: true }`; tests that
+ * deliberately put malformed MCP on the wire pass `{ strictValidation: false }`.
+ * `entry` overrides the hosting options of the createMcpHandler entry arms
+ * (ignored by every other transport).
  */
-export async function wire(transport: Transport, makeServer: ServerFactory, client: Client, sniff: SnifferOptions = {}): Promise<Wired> {
+export interface WireOptions extends SnifferOptions {
+ /**
+ * createMcpHandler hosting overrides for the entry arms. Defaults:
+ * `{ legacy: 'stateless' }` on entryStateless (the canonical slot value) and
+ * modern-only strict (no legacy slot) on entryModern. `onerror` and
+ * `responseMode` pass through unchanged.
+ */
+ entry?: CreateMcpHandlerOptions;
+}
+
+export async function wire(
+ transport: Transport,
+ makeServer: ServerFactory | EntryServerFactory,
+ client: Client,
+ sniff: WireOptions = {}
+): Promise<Wired> {
  switch (transport) {
  case 'inMemory': {
  const server = makeServer();
@@ -67,6 +130,47 @@ export async function wire(transport: Transport, makeServer: ServerFactory, clie
  [Symbol.asyncDispose]: () => Promise.all([client.close(), handle.close()]).then(() => {})
  };
  }
+ case 'entryStateless':
+ case 'entryModern': {
+ // The dual-era HTTP entry (`createMcpHandler`) hosted in process via an
+ // injected fetch, exactly like the other HTTP arms. The scenario factory
+ // backs the entry directly (the entry calls it once per request with its
+ // per-request context). `entryStateless` serves the scenario's plain
+ // client through the entry's `legacy: 'stateless'` slot; `entryModern`
+ // keeps the endpoint modern-only strict and connects the client on the
+ // 2026-07-28 revision (pin-mode negotiation + the per-request envelope
+ // stop-gap). Every HTTP exchange is recorded on `httpLog`.
+ const handler = createMcpHandler(
+ makeServer,
+ transport === 'entryStateless' ? { legacy: 'stateless', ...sniff.entry } : { ...sniff.entry }
+ );
+ const url = new URL('http://in-process/mcp');
+ const httpLog: RecordedHttpExchange[] = [];
+ const fetch = async (u: URL | string, init?: RequestInit) => {
+ const request = new Request(u, init);
+ const response = await handler.fetch(request);
+ httpLog.push({
+ method: request.method.toUpperCase(),
+ ...(typeof init?.body === 'string' && { requestBody: init.body }),
+ status: response.status,
+ contentType: response.headers.get('content-type') ?? '',
+ response: response.clone()
+ });
+ return response;
+ };
+ let clientTx = new StreamableHTTPClientTransport(url, { fetch });
+ if (transport === 'entryModern') {
+ pinModernNegotiation(client);
+ clientTx = attachModernEnvelope(clientTx);
+ }
+ await client.connect(sniffTransport(clientTx, 'client', sniff));
+ return {
+ fetch,
+ url,
+ httpLog,
+ [Symbol.asyncDispose]: () => Promise.all([client.close(), handler.close()]).then(() => {})
+ };
+ }
  case 'sse': {
  // The legacy SSE transport needs a real socket: the factory's server is hosted on the
  // shipped SSEServerTransport (@modelcontextprotocol/server-legacy/sse) behind a loopback
@@ -212,6 +316,78 @@ export function hostStateless(makeServer: ServerFactory): { handleRequest: HttpH
  };
 }
 
+// ───────────────────────────────────────────────────────────────────────────────
+// createMcpHandler entry arms (entryStateless / entryModern) — client-side shims
+// ───────────────────────────────────────────────────────────────────────────────
+
+/** The protocol revision the entryModern arm negotiates and claims per request. */
+const MODERN_REVISION: SpecVersion = '2026-07-28';
+
+/**
+ * The per-request `_meta` envelope of a 2026-07-28 request, for scenario bodies
+ * that put raw HTTP requests on the wire (via `wired.fetch`) rather than going
+ * through the wired client. Typed calls through the wired client never need
+ * this — the entryModern arm attaches the envelope itself (see
+ * {@linkcode attachModernEnvelope}).
+ */
+export function modernEnvelopeMeta(clientInfo?: Implementation): Record<string, unknown> {
+ return {
+ [PROTOCOL_VERSION_META_KEY]: MODERN_REVISION,
+ [CLIENT_INFO_META_KEY]: clientInfo ?? { name: 'e2e-entry-client', version: '1.0.0' },
+ [CLIENT_CAPABILITIES_META_KEY]: {}
+ };
+}
+
+/**
+ * Put the (already constructed) scenario client into pinned 2026-07-28
+ * negotiation. Version negotiation is a constructor-only option and the
+ * scenario corpus constructs era-agnostic clients, so the entryModern arm flips
+ * the option on the instance before `connect()` — a harness stop-gap, not a
+ * public API. Clients that already opted into a negotiation mode are left
+ * untouched (their cells deliberately exercise that mode).
+ */
+function pinModernNegotiation(client: Client): void {
+ const internals = client as unknown as { _versionNegotiation?: { mode?: unknown } };
+ internals._versionNegotiation ??= { mode: { pin: MODERN_REVISION } };
+}
+
+/**
+ * The per-request `_meta` envelope stop-gap for the entryModern arm: the
+ * negotiating client only attaches the envelope to its `server/discover` probe
+ * today (automatic per-request emission is a client-side follow-up), so the
+ * harness re-attaches the same envelope to every later request and notification
+ * the scenario's typed calls put on the wire. The envelope is captured from the
+ * probe itself, so it always matches what the client actually claimed; messages
+ * that already carry a protocol-version claim (the probe, or a scenario's
+ * explicitly enveloped request) pass through untouched.
+ *
+ * Applied beneath the wire sniffer and `tapWire`, so recorded traffic shows the
+ * messages exactly as the scenario sent them while the wire carries the
+ * envelope the entry requires.
+ */
+function attachModernEnvelope<T extends SdkTransport>(transport: T): T {
+ let envelope: Record<string, unknown> | undefined;
+ const origSend = transport.send.bind(transport);
+ transport.send = async (message, opts) => {
+ let outbound = message;
+ if ('method' in message) {
+ const params = (message.params ?? {}) as { _meta?: Record<string, unknown> };
+ const meta = params._meta;
+ if (meta?.[PROTOCOL_VERSION_META_KEY] !== undefined) {
+ envelope ??= {
+ [PROTOCOL_VERSION_META_KEY]: meta[PROTOCOL_VERSION_META_KEY],
+ [CLIENT_INFO_META_KEY]: meta[CLIENT_INFO_META_KEY],
+ [CLIENT_CAPABILITIES_META_KEY]: meta[CLIENT_CAPABILITIES_META_KEY]
+ };
+ } else if (envelope !== undefined) {
+ outbound = { ...message, params: { ...params, _meta: { ...envelope, ...meta } } };
+ }
+ }
+ return origSend(outbound, opts);
+ };
+ return transport;
+}
+
 // ───────────────────────────────────────────────────────────────────────────────
 // In-process stdio client — TEST-ONLY
 //

test/e2e/helpers/verifies.ts

@@ -18,11 +18,23 @@
 import { describe, test } from 'vitest';
 
 import { REQUIREMENTS } from '../requirements.js';
-import type { TestArgs } from '../types.js';
-import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS } from '../types.js';
+import type { Requirement, SpecVersion, TestArgs, Transport } from '../types.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from '../types.js';
 
 type TestBody = (args: TestArgs) => Promise<void>;
 
+/** Whether a requirement's `entryExclusions` keep the given entry arm out of its cells. */
+function excludedFromEntryArm(req: Requirement, transport: Transport): boolean {
+ if (!(ENTRY_TRANSPORTS as readonly Transport[]).includes(transport)) return false;
+ return (req.entryExclusions ?? []).some(x => x.arm === undefined || x.arm === transport);
+}
+
+/** Whether a transport arm serves the given spec version (era-fixed arms serve exactly one). */
+function transportServesVersion(transport: Transport, version: SpecVersion): boolean {
+ const versions = TRANSPORT_SPEC_VERSIONS[transport];
+ return versions === undefined || versions.includes(version);
+}
+
 export function verifies(id: string | readonly string[], fn: TestBody, opts?: { title?: string }): void {
  const ids = Array.isArray(id) ? id : [id];
  for (const rid of ids) registerOne(rid, fn, opts);
@@ -33,13 +45,13 @@ function registerOne(id: string, fn: TestBody, opts?: { title?: string }): void
  if (!req) throw new Error(`verifies('${id}'): unknown requirement id`);
  if (req.deferred) throw new Error(`verifies('${id}'): requirement is deferred — drop the deferral or the test`);
 
- const transports = req.transports ?? ALL_TRANSPORTS;
+ const transports = (req.transports ?? ALL_TRANSPORTS).filter(t => !excludedFromEntryArm(req, t));
  const versions = ALL_SPEC_VERSIONS.filter(
  v =>
  (req.addedInSpecVersion === undefined || v >= req.addedInSpecVersion) &&
  (req.removedInSpecVersion === undefined || v < req.removedInSpecVersion)
  );
- const cells = versions.flatMap(v => transports.map(t => [t, v] as const));
+ const cells = versions.flatMap(v => transports.filter(t => transportServesVersion(t, v)).map(t => [t, v] as const));
 
  describe.each(cells)(`${id} [%s %s]`, (transport, protocolVersion) => {
  const kf = req.knownFailures?.find(

test/e2e/CLAUDE.md

@@ -58,6 +58,26 @@ note: 'stateless hosting has no server→client back-channel'
 `addedInSpecVersion` / `removedInSpecVersion` bound the spec versions a requirement applies to. A behavior changed by a spec release gets a sibling entry: the new entry lists every retired id it replaces in `supersedes` (an array, requires `addedInSpecVersion`), and each retired
 entry points back via `supersededBy` (requires `removedInSpecVersion`). A coverage gate enforces that the links resolve and are exactly symmetric.
 
+## The createMcpHandler entry arms (entryStateless / entryModern)
+
+Two transport arms host the dual-era HTTP entry (`createMcpHandler`) in process via an injected fetch, exactly like the other HTTP arms. They are era-fixed (`TRANSPORT_SPEC_VERSIONS`), so each registers cells on exactly one spec-version axis:
+
+- `entryStateless` — the entry with the `legacy: 'stateless'` slot; the scenario's plain client is served per request through the slot. Cells run on the 2025-11-25 axis only.
+- `entryModern` — the entry modern-only strict (no legacy slot); the scenario's client is put into pinned 2026-07-28 negotiation by the arm and the per-request `_meta` envelope is attached to every outgoing request/notification by the arm (a harness stop-gap until the client
+ emits it itself). Cells run on the 2026-07-28 axis only.
+
+Both arms are part of the default transport list, so unrestricted requirements run through the entry automatically. When a requirement cannot run on an entry arm, annotate it with a machine-readable reason instead of bending the test:
+
+```ts
+entryExclusions: [{ arm: 'entryModern', reason: 'method-not-in-modern-registry' /* optional note */ }];
+```
+
+Omitting `arm` excludes both arms. The reasons (`EntryExclusionReason` in types.ts) are the acceptance checklist for re-admitting cells when the corresponding entry feature lands; a coverage gate rejects annotations that would never have an effect. Requirement families that the
+per-request entry structurally cannot serve at all (server→client requests, sessions/resumability, standalone GET streams, subscriptions) are already expressed through their `transports` restrictions and need no annotation.
+
+Arm-specific helpers: `wire()`'s fourth argument also accepts `entry` (createMcpHandler hosting overrides — e.g. a `responseMode` or a bring-your-own `legacy` slot value), the returned `Wired.httpLog` records every HTTP exchange (request body, status, content-type, a readable
+response clone) for raw wire assertions, factories may accept the optional per-request context (`EntryServerFactory`), and `modernEnvelopeMeta()` builds the envelope for bodies that POST raw 2026-era requests through `wired.fetch`.
+
 ## Running
 
 From the repo root (the suite is the `@modelcontextprotocol/test-e2e` workspace package):

test/e2e/coverage.test.ts

@@ -14,6 +14,7 @@ import { fileURLToPath } from 'node:url';
 import { expect, test } from 'vitest';
 
 import { REQUIREMENTS } from './requirements.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from './types.js';
 
 const E2E_DIR = path.dirname(fileURLToPath(import.meta.url));
 
@@ -88,6 +89,34 @@ test('every transport-restricted requirement explains why in note', () => {
  expect(missing).toEqual([]);
 });
 
+test('every entryExclusions annotation targets an entry arm the requirement would otherwise run on', () => {
+ const bad: string[] = [];
+ for (const [id, r] of Object.entries(REQUIREMENTS)) {
+ for (const exclusion of r.entryExclusions ?? []) {
+ const arms = exclusion.arm === undefined ? ENTRY_TRANSPORTS : [exclusion.arm];
+ for (const arm of arms) {
+ const transports = r.transports ?? ALL_TRANSPORTS;
+ if (!transports.includes(arm)) {
+ bad.push(`${id}: entryExclusions targets '${arm}', which the requirement's transports never include`);
+ continue;
+ }
+ const versions = ALL_SPEC_VERSIONS.filter(
+ v =>
+ (r.addedInSpecVersion === undefined || v >= r.addedInSpecVersion) &&
+ (r.removedInSpecVersion === undefined || v < r.removedInSpecVersion) &&
+ (TRANSPORT_SPEC_VERSIONS[arm]?.includes(v) ?? true)
+ );
+ if (versions.length === 0) {
+ bad.push(
+ `${id}: entryExclusions targets '${arm}', which registers no cells within the requirement's spec-version bounds`
+ );
+ }
+ }
+ }
+ }
+ expect(bad).toEqual([]);
+});
+
 test('supersedes/supersededBy links are symmetric and resolve', () => {
  const bad: string[] = [];
  for (const [id, req] of Object.entries(REQUIREMENTS)) {

test/e2e/fixtures/dual-era-stdio-server.ts

@@ -0,0 +1,29 @@
+/**
+ * Runnable dual-era stdio MCP server fixture for the dual-era stdio e2e cells.
+ *
+ * `eraSupport: 'dual-era'` is the single declared act on an otherwise ordinary
+ * hand-constructed McpServer connected to the unchanged StdioServerTransport.
+ * Spawned as a real child process (via tsx) by
+ * test/e2e/scenarios/stdio-dual-era.test.ts; exits when its stdin reaches EOF.
+ */
+
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import { z } from 'zod/v4';
+
+const server = new McpServer(
+ { name: 'dual-era-stdio-e2e-fixture', version: '1.0.0' },
+ { capabilities: { tools: {} }, eraSupport: 'dual-era' }
+);
+
+server.registerTool(
+ 'echo',
+ {
+ description: 'Echoes the input text back as a text content block.',
+ inputSchema: z.object({ text: z.string() })
+ },
+ ({ text }) => ({ content: [{ type: 'text', text }] })
+);
+
+await server.connect(new StdioServerTransport());
+process.stderr.write('[dual-era-stdio-server] ready\n');

test/e2e/helpers/index.ts

@@ -15,30 +15,93 @@ import { PassThrough } from 'node:stream';
 
 import type { Client } from '@modelcontextprotocol/client';
 import { SSEClientTransport, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
-import type { EventStore, JSONRPCMessage, McpServer, Server } from '@modelcontextprotocol/server';
-import { InMemoryTransport, ReadBuffer, serializeMessage, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import { CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY } from '@modelcontextprotocol/core';
+import type {
+ CreateMcpHandlerOptions,
+ EventStore,
+ Implementation,
+ JSONRPCMessage,
+ McpRequestContext,
+ McpServer,
+ Server,
+ Transport as SdkTransport
+} from '@modelcontextprotocol/server';
+import {
+ createMcpHandler,
+ InMemoryTransport,
+ ReadBuffer,
+ serializeMessage,
+ WebStandardStreamableHTTPServerTransport
+} from '@modelcontextprotocol/server';
 import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 
-import type { Transport } from '../types.js';
+import type { SpecVersion, Transport } from '../types.js';
 import { startLegacySseHost } from './sse-host.js';
 import type { SnifferOptions } from './wire-sniffer.js';
 import { sniffTransport } from './wire-sniffer.js';
 
 export type ServerFactory = () => McpServer | Server;
 
+/**
+ * A factory that optionally consumes the createMcpHandler per-request context.
+ * The context is only supplied on the entry arms (where the entry constructs a
+ * fresh instance per request); on every other arm the factory is called with no
+ * arguments, so declare the parameter optional.
+ */
+export type EntryServerFactory = (ctx?: McpRequestContext) => McpServer | Server;
+
+/** One HTTP exchange recorded by the entry arms (see {@linkcode Wired.httpLog}). */
+export interface RecordedHttpExchange {
+ /** HTTP request method (GET/POST/DELETE). */
+ method: string;
+ /** The request body text, when one was sent as a string. */
+ requestBody?: string;
+ /** HTTP response status. */
+ status: number;
+ /** Response content-type header (empty string when absent). */
+ contentType: string;
+ /** An unread clone of the HTTP response, for byte-level assertions (`await exchange.response.text()`). */
+ response: Response;
+}
+
 export interface Wired extends AsyncDisposable {
  readonly fetch?: (url: URL | string, init?: RequestInit) => Promise<Response>;
  readonly url?: URL;
+ /**
+ * Every HTTP exchange the wired client performed, in order, including the
+ * connect-time negotiation. Recorded by the createMcpHandler entry arms
+ * only — scenarios on those arms use it to assert raw wire facts (request
+ * bodies, response status/content-type/bytes) that the typed client API
+ * does not expose.
+ */
+ readonly httpLog?: readonly RecordedHttpExchange[];
 }
 
 /**
- * The fourth argument controls the wire-format sniffer (see wire-sniffer.ts):
- * every message the client sends or receives is validated against the SDK's
- * spec-anchored Zod schemas. Tests that intentionally use vendor-extension
- * methods pass `{ allowCustomMethods: true }`; tests that deliberately put
- * malformed MCP on the wire pass `{ strictValidation: false }`.
+ * The fourth argument's sniffer options control the wire-format sniffer (see
+ * wire-sniffer.ts): every message the client sends or receives is validated
+ * against the SDK's spec-anchored Zod schemas. Tests that intentionally use
+ * vendor-extension methods pass `{ allowCustomMethods: true }`; tests that
+ * deliberately put malformed MCP on the wire pass `{ strictValidation: false }`.
+ * `entry` overrides the hosting options of the createMcpHandler entry arms
+ * (ignored by every other transport).
  */
-export async function wire(transport: Transport, makeServer: ServerFactory, client: Client, sniff: SnifferOptions = {}): Promise<Wired> {
+export interface WireOptions extends SnifferOptions {
+ /**
+ * createMcpHandler hosting overrides for the entry arms. Defaults:
+ * `{ legacy: 'stateless' }` on entryStateless (the canonical slot value) and
+ * modern-only strict (no legacy slot) on entryModern. `onerror` and
+ * `responseMode` pass through unchanged.
+ */
+ entry?: CreateMcpHandlerOptions;
+}
+
+export async function wire(
+ transport: Transport,
+ makeServer: ServerFactory | EntryServerFactory,
+ client: Client,
+ sniff: WireOptions = {}
+): Promise<Wired> {
  switch (transport) {
  case 'inMemory': {
  const server = makeServer();
@@ -67,6 +130,47 @@ export async function wire(transport: Transport, makeServer: ServerFactory, clie
  [Symbol.asyncDispose]: () => Promise.all([client.close(), handle.close()]).then(() => {})
  };
  }
+ case 'entryStateless':
+ case 'entryModern': {
+ // The dual-era HTTP entry (`createMcpHandler`) hosted in process via an
+ // injected fetch, exactly like the other HTTP arms. The scenario factory
+ // backs the entry directly (the entry calls it once per request with its
+ // per-request context). `entryStateless` serves the scenario's plain
+ // client through the entry's `legacy: 'stateless'` slot; `entryModern`
+ // keeps the endpoint modern-only strict and connects the client on the
+ // 2026-07-28 revision (pin-mode negotiation + the per-request envelope
+ // stop-gap). Every HTTP exchange is recorded on `httpLog`.
+ const handler = createMcpHandler(
+ makeServer,
+ transport === 'entryStateless' ? { legacy: 'stateless', ...sniff.entry } : { ...sniff.entry }
+ );
+ const url = new URL('http://in-process/mcp');
+ const httpLog: RecordedHttpExchange[] = [];
+ const fetch = async (u: URL | string, init?: RequestInit) => {
+ const request = new Request(u, init);
+ const response = await handler.fetch(request);
+ httpLog.push({
+ method: request.method.toUpperCase(),
+ ...(typeof init?.body === 'string' && { requestBody: init.body }),
+ status: response.status,
+ contentType: response.headers.get('content-type') ?? '',
+ response: response.clone()
+ });
+ return response;
+ };
+ let clientTx = new StreamableHTTPClientTransport(url, { fetch });
+ if (transport === 'entryModern') {
+ pinModernNegotiation(client);
+ clientTx = attachModernEnvelope(clientTx);
+ }
+ await client.connect(sniffTransport(clientTx, 'client', sniff));
+ return {
+ fetch,
+ url,
+ httpLog,
+ [Symbol.asyncDispose]: () => Promise.all([client.close(), handler.close()]).then(() => {})
+ };
+ }
  case 'sse': {
  // The legacy SSE transport needs a real socket: the factory's server is hosted on the
  // shipped SSEServerTransport (@modelcontextprotocol/server-legacy/sse) behind a loopback
@@ -212,6 +316,78 @@ export function hostStateless(makeServer: ServerFactory): { handleRequest: HttpH
  };
 }
 
+// ───────────────────────────────────────────────────────────────────────────────
+// createMcpHandler entry arms (entryStateless / entryModern) — client-side shims
+// ───────────────────────────────────────────────────────────────────────────────
+
+/** The protocol revision the entryModern arm negotiates and claims per request. */
+const MODERN_REVISION: SpecVersion = '2026-07-28';
+
+/**
+ * The per-request `_meta` envelope of a 2026-07-28 request, for scenario bodies
+ * that put raw HTTP requests on the wire (via `wired.fetch`) rather than going
+ * through the wired client. Typed calls through the wired client never need
+ * this — the entryModern arm attaches the envelope itself (see
+ * {@linkcode attachModernEnvelope}).
+ */
+export function modernEnvelopeMeta(clientInfo?: Implementation): Record<string, unknown> {
+ return {
+ [PROTOCOL_VERSION_META_KEY]: MODERN_REVISION,
+ [CLIENT_INFO_META_KEY]: clientInfo ?? { name: 'e2e-entry-client', version: '1.0.0' },
+ [CLIENT_CAPABILITIES_META_KEY]: {}
+ };
+}
+
+/**
+ * Put the (already constructed) scenario client into pinned 2026-07-28
+ * negotiation. Version negotiation is a constructor-only option and the
+ * scenario corpus constructs era-agnostic clients, so the entryModern arm flips
+ * the option on the instance before `connect()` — a harness stop-gap, not a
+ * public API. Clients that already opted into a negotiation mode are left
+ * untouched (their cells deliberately exercise that mode).
+ */
+function pinModernNegotiation(client: Client): void {
+ const internals = client as unknown as { _versionNegotiation?: { mode?: unknown } };
+ internals._versionNegotiation ??= { mode: { pin: MODERN_REVISION } };
+}
+
+/**
+ * The per-request `_meta` envelope stop-gap for the entryModern arm: the
+ * negotiating client only attaches the envelope to its `server/discover` probe
+ * today (automatic per-request emission is a client-side follow-up), so the
+ * harness re-attaches the same envelope to every later request and notification
+ * the scenario's typed calls put on the wire. The envelope is captured from the
+ * probe itself, so it always matches what the client actually claimed; messages
+ * that already carry a protocol-version claim (the probe, or a scenario's
+ * explicitly enveloped request) pass through untouched.
+ *
+ * Applied beneath the wire sniffer and `tapWire`, so recorded traffic shows the
+ * messages exactly as the scenario sent them while the wire carries the
+ * envelope the entry requires.
+ */
+function attachModernEnvelope<T extends SdkTransport>(transport: T): T {
+ let envelope: Record<string, unknown> | undefined;
+ const origSend = transport.send.bind(transport);
+ transport.send = async (message, opts) => {
+ let outbound = message;
+ if ('method' in message) {
+ const params = (message.params ?? {}) as { _meta?: Record<string, unknown> };
+ const meta = params._meta;
+ if (meta?.[PROTOCOL_VERSION_META_KEY] !== undefined) {
+ envelope ??= {
+ [PROTOCOL_VERSION_META_KEY]: meta[PROTOCOL_VERSION_META_KEY],
+ [CLIENT_INFO_META_KEY]: meta[CLIENT_INFO_META_KEY],
+ [CLIENT_CAPABILITIES_META_KEY]: meta[CLIENT_CAPABILITIES_META_KEY]
+ };
+ } else if (envelope !== undefined) {
+ outbound = { ...message, params: { ...params, _meta: { ...envelope, ...meta } } };
+ }
+ }
+ return origSend(outbound, opts);
+ };
+ return transport;
+}
+
 // ───────────────────────────────────────────────────────────────────────────────
 // In-process stdio client — TEST-ONLY
 //

test/e2e/helpers/verifies.ts

@@ -18,11 +18,23 @@
 import { describe, test } from 'vitest';
 
 import { REQUIREMENTS } from '../requirements.js';
-import type { TestArgs } from '../types.js';
-import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS } from '../types.js';
+import type { Requirement, SpecVersion, TestArgs, Transport } from '../types.js';
+import { ALL_SPEC_VERSIONS, ALL_TRANSPORTS, ENTRY_TRANSPORTS, TRANSPORT_SPEC_VERSIONS } from '../types.js';
 
 type TestBody = (args: TestArgs) => Promise<void>;
 
+/** Whether a requirement's `entryExclusions` keep the given entry arm out of its cells. */
+function excludedFromEntryArm(req: Requirement, transport: Transport): boolean {
+ if (!(ENTRY_TRANSPORTS as readonly Transport[]).includes(transport)) return false;
+ return (req.entryExclusions ?? []).some(x => x.arm === undefined || x.arm === transport);
+}
+
+/** Whether a transport arm serves the given spec version (era-fixed arms serve exactly one). */
+function transportServesVersion(transport: Transport, version: SpecVersion): boolean {
+ const versions = TRANSPORT_SPEC_VERSIONS[transport];
+ return versions === undefined || versions.includes(version);
+}
+
 export function verifies(id: string | readonly string[], fn: TestBody, opts?: { title?: string }): void {
  const ids = Array.isArray(id) ? id : [id];
  for (const rid of ids) registerOne(rid, fn, opts);
@@ -33,13 +45,13 @@ function registerOne(id: string, fn: TestBody, opts?: { title?: string }): void
  if (!req) throw new Error(`verifies('${id}'): unknown requirement id`);
  if (req.deferred) throw new Error(`verifies('${id}'): requirement is deferred — drop the deferral or the test`);
 
- const transports = req.transports ?? ALL_TRANSPORTS;
+ const transports = (req.transports ?? ALL_TRANSPORTS).filter(t => !excludedFromEntryArm(req, t));
  const versions = ALL_SPEC_VERSIONS.filter(
  v =>
  (req.addedInSpecVersion === undefined || v >= req.addedInSpecVersion) &&
  (req.removedInSpecVersion === undefined || v < req.removedInSpecVersion)
  );
- const cells = versions.flatMap(v => transports.map(t => [t, v] as const));
+ const cells = versions.flatMap(v => transports.filter(t => transportServesVersion(t, v)).map(t => [t, v] as const));
 
  describe.each(cells)(`${id} [%s %s]`, (transport, protocolVersion) => {
  const kf = req.knownFailures?.find(