Implement MCP 2026-07-28 (#2286)

Co-authored-by: Matt <77928207+mattzcarey@users.noreply.github.com>
Co-authored-by: Konstantin Konstantinov <KKonstantinov@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

examples/dual-era/README.md

@@ -0,0 +1,12 @@
+# dual-era
+
+One server factory, both protocol eras (2025 `initialize` and 2026-07-28 per-request envelope), both transports (stdio and Streamable HTTP). The client connects once as a plain 2025 client and once with `versionNegotiation: { mode: 'auto' }`; the same `greet` tool answers both
+and reports which era served the call.
+
+This is the recommended **first** example to read if you are migrating an existing server to the 2026 era: the entry (`serveStdio` / `createMcpHandler`) owns the era decision, the factory is era-agnostic.
+
+```bash
+pnpm tsx examples/dual-era/client.ts                              # stdio
+pnpm tsx examples/dual-era/server.ts --http --port 3000           # term 1
+pnpm tsx examples/dual-era/client.ts --http http://127.0.0.1:3000/ # term 2
+```

examples/dual-era/client.ts

@@ -0,0 +1,49 @@
+/**
+ * Drives the dual-era server (`./server.ts`) over the selected transport with
+ * BOTH kinds of client:
+ *
+ * 1. a plain 2025 client (`versionNegotiation: { mode: 'legacy' }`) — the
+ *    `initialize` handshake, served exactly as today (the server reports
+ *    `era === 'legacy'`);
+ * 2. a 2026-capable client (`versionNegotiation: { mode: 'auto' }`) — the
+ *    `server/discover` probe negotiates the 2026-07-28 revision (no
+ *    `initialize` is ever sent) and the SDK attaches the per-request `_meta`
+ *    envelope itself (the server reports `era === 'modern'`).
+ *
+ * Asserts both legs and exits 0 — used as a self-verifying e2e by
+ * `scripts/examples/run-examples.ts` over stdio AND http.
+ */
+import { check, parseExampleArgs, siblingPath } from '@mcp-examples/shared';
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+
+// The story body drives BOTH eras itself, so the argv `era` flag is unused;
+// only the transport leg is read from argv.
+const { transport, url } = parseExampleArgs();
+
+const connect = async (mode: 'legacy' | 'auto'): Promise<Client> => {
+    const client = new Client({ name: 'dual-era-example-client', version: '1.0.0' }, { versionNegotiation: { mode } });
+    await (transport === 'stdio'
+        ? client.connect(new StdioClientTransport({ command: 'npx', args: ['-y', 'tsx', siblingPath(import.meta.url, 'server.ts')] }))
+        : client.connect(new StreamableHTTPClientTransport(new URL(url))));
+    return client;
+};
+
+// --- leg 1: plain 2025 client (initialize handshake) ---
+const legacy = await connect('legacy');
+const legacyTools = await legacy.listTools();
+check.ok(legacyTools.tools.some(t => t.name === 'greet'));
+const legacyGreet = await legacy.callTool({ name: 'greet', arguments: { name: '2025 client' } });
+const legacyText = legacyGreet.content?.[0]?.type === 'text' ? legacyGreet.content[0].text : '';
+check.match(legacyText, /Hello, 2025 client! \(served on the legacy protocol era\)/);
+await legacy.close();
+
+// --- leg 2: 2026-capable client (server/discover negotiation) ---
+const modern = await connect('auto');
+check.equal(modern.getNegotiatedProtocolVersion(), '2026-07-28');
+const modernGreet = await modern.callTool({ name: 'greet', arguments: { name: '2026 client' } });
+const modernText = modernGreet.content?.[0]?.type === 'text' ? modernGreet.content[0].text : '';
+check.match(modernText, /Hello, 2026 client! \(served on the modern protocol era\)/);
+await modern.close();
+
+console.log('both eras served by the same factory over the same transport.');

examples/dual-era/package.json

@@ -0,0 +1,23 @@
+{
+    "name": "@mcp-examples/dual-era",
+    "private": true,
+    "type": "module",
+    "scripts": {
+        "server": "tsx server.ts",
+        "client": "tsx client.ts"
+    },
+    "dependencies": {
+        "@mcp-examples/shared": "workspace:*",
+        "@modelcontextprotocol/client": "workspace:*",
+        "@modelcontextprotocol/node": "workspace:*",
+        "@modelcontextprotocol/server": "workspace:*",
+        "zod": "catalog:runtimeShared"
+    },
+    "devDependencies": {
+        "tsx": "catalog:devTools"
+    },
+    "example": {
+        "era": "modern",
+        "//": "The story body drives BOTH eras itself (legacy via { mode: 'legacy' }, modern via { mode: 'auto' }); pinned so the runner runs it once per transport."
+    }
+}

examples/dual-era/server.ts

@@ -0,0 +1,55 @@
+/**
+ * Dual-era serving from one factory, both transports.
+ *
+ * The same factory backs both protocol eras: a 2025-era client connects with
+ * the `initialize` handshake; a 2026-capable client
+ * (`versionNegotiation: { mode: 'auto' }`) probes with `server/discover`,
+ * negotiates the 2026-07-28 revision, and the SDK attaches the per-request
+ * `_meta` envelope to every outgoing request itself. Tools are defined once
+ * and served identically to either kind of client.
+ *
+ * One binary, either transport (selected from argv): stdio by default
+ * (`serveStdio(buildServer)`), or HTTP under `--http --port <N>`
+ * (`createMcpHandler(buildServer)` on its default posture — modern served per
+ * request, 2025-era traffic served stateless from the same factory).
+ */
+import { createServer } from 'node:http';
+
+import { parseExampleArgs } from '@mcp-examples/shared';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+import type { CallToolResult, McpRequestContext } from '@modelcontextprotocol/server';
+import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import * as z from 'zod/v4';
+
+const buildServer = (ctx: McpRequestContext): McpServer => {
+    const server = new McpServer(
+        { name: 'dual-era-server', version: '1.0.0' },
+        { capabilities: { tools: {} }, instructions: 'A small dual-era demo server.' }
+    );
+
+    server.registerTool(
+        'greet',
+        {
+            description: 'Greets the caller and reports which protocol era served the request',
+            inputSchema: z.object({ name: z.string().describe('Name to greet') })
+        },
+        async ({ name }): Promise<CallToolResult> => ({
+            content: [{ type: 'text', text: `Hello, ${name}! (served on the ${ctx.era} protocol era)` }]
+        })
+    );
+
+    return server;
+};
+
+const { transport, port } = parseExampleArgs();
+
+if (transport === 'stdio') {
+    void serveStdio(buildServer);
+    console.error('[server] serving over stdio');
+} else {
+    const handler = createMcpHandler(buildServer);
+    createServer(toNodeHandler(handler)).listen(port, () => {
+        console.error(`[server] listening on http://127.0.0.1:${port}/mcp`);
+    });
+}