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/sampling/README.md

@@ -0,0 +1,20 @@
+# sampling
+
+A tool that asks the host LLM for a completion. One factory, both protocol eras: sampling works on both eras with different APIs — push-style on 2025, `inputRequired` on 2026; the protocol carries the `sampling/createMessage` request differently but the user experience is the
+same.
+
+| 2025-era (`--legacy`, push-style)                                                                                                                | 2026-07-28 (multi-round-trip)                                                                                                                                                                 |
+| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `await ctx.mcpReq.requestSampling({ messages, maxTokens })` — the server pushes a `sampling/createMessage` request and awaits the answer in-line | `return inputRequired({ inputRequests: { summary: inputRequired.createMessage({ messages, maxTokens }) } })` — the client fulfils the embedded request and retries with the response attached |
+
+The client registers **one** `sampling/createMessage` handler; on the 2026-07-28 leg the auto-fulfilment driver dispatches the embedded request to that same handler.
+
+> Push-style sampling is **deprecated** as of protocol revision 2026-07-28 (SEP-2577) but remains functional during the deprecation window.
+
+Push-style sampling is exercised on **stdio/legacy** (`createMcpHandler`'s stateless-legacy posture has no return path for the client's response POST — see `../legacy-routing/` for the sessionful composition); the http/legacy leg only verifies the initialize handshake.
+2026-07-28 `inputRequired.createMessage` runs on both transports.
+
+```bash
+pnpm --filter @mcp-examples/sampling client               # 2026-07-28 (inputRequired)
+pnpm --filter @mcp-examples/sampling client -- --legacy   # 2025 (push-style)
+```

examples/sampling/client.ts

@@ -0,0 +1,52 @@
+/**
+ * Advertises the sampling capability, registers a `sampling/createMessage`
+ * handler that returns a canned summary, then calls the `summarize` tool and
+ * asserts the canned text round-tripped.
+ *
+ * The same handler serves both protocol eras: on the 2025-era leg
+ * (`--legacy`) the server pushes `sampling/createMessage` and this handler
+ * answers it directly; on the 2026-07-28 leg the auto-fulfilment driver
+ * dispatches the embedded `sampling/createMessage` from the server's
+ * `inputRequired` result to this same handler, then retries the tool call
+ * with the response attached.
+ */
+import { check, parseExampleArgs, siblingPath } from '@mcp-examples/shared';
+import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+
+const { transport, url, era } = parseExampleArgs();
+
+const client = new Client(
+    { name: 'sampling-example-client', version: '1.0.0' },
+    {
+        versionNegotiation: { mode: era === 'modern' ? 'auto' : 'legacy' },
+        capabilities: { sampling: {} }
+    }
+);
+
+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))));
+
+client.setRequestHandler('sampling/createMessage', async () => ({
+    role: 'assistant',
+    content: { type: 'text', text: '[canned summary]' },
+    model: 'stub',
+    stopReason: 'endTurn'
+}));
+
+if (transport === 'http' && era === 'legacy') {
+    // Push-style `ctx.mcpReq.requestSampling` needs a sessionful return
+    // path: the client's response to `sampling/createMessage` is a separate
+    // POST that must reach the SAME server instance that sent the request.
+    // `createMcpHandler`'s default stateless-legacy posture has no such
+    // path — see `../legacy-routing/` for the sessionful `isLegacyRequest`
+    // composition. The push-style flow is exercised on stdio/legacy; this
+    // leg only verifies the 2025 `initialize` handshake succeeded.
+    check.ok(client.getServerCapabilities()?.tools);
+} else {
+    const result = await client.callTool({ name: 'summarize', arguments: { text: 'hello world' } });
+    check.equal(result.content?.[0]?.type === 'text' ? result.content[0].text : '', '[canned summary]');
+}
+
+await client.close();

examples/sampling/package.json

@@ -0,0 +1,23 @@
+{
+    "name": "@mcp-examples/sampling",
+    "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": "dual",
+        "//": "2025-era push-style ctx.mcpReq.requestSampling is exercised on stdio/legacy (createMcpHandler's stateless-legacy posture has no return path for the client's response POST — see ../legacy-routing/ for the sessionful composition); 2026-07-28 inputRequired.createMessage runs on both transports."
+    }
+}

examples/sampling/server.ts

@@ -0,0 +1,77 @@
+/**
+ * Sampling — a tool that asks the host LLM for a completion. One factory,
+ * both protocol eras.
+ *
+ * The same tool serves both eras with different APIs: on a 2025-era
+ * connection (`--legacy`, the `initialize` handshake) the server uses the
+ * push-style server→client request flow — `ctx.mcpReq.requestSampling(...)`
+ * sends `sampling/createMessage` and awaits the answer in-line. On a
+ * 2026-07-28 connection there is no server→client request channel: the same
+ * tool instead **returns** `inputRequired(...)` with an embedded
+ * `sampling/createMessage`, and the client retries with the model's response
+ * attached. The protocol carries the request differently; the user
+ * experience is the same.
+ *
+ * One binary, either transport. Logs go to stderr only — stdio's stdout is
+ * the JSON-RPC stream.
+ */
+import { createServer } from 'node:http';
+
+import { parseExampleArgs } from '@mcp-examples/shared';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+import type { CallToolResult, InputRequiredResult, McpRequestContext } from '@modelcontextprotocol/server';
+import { createMcpHandler, inputRequired, McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import * as z from 'zod/v4';
+
+function buildServer(reqCtx: McpRequestContext): McpServer {
+    const server = new McpServer({ name: 'sampling-example', version: '1.0.0' });
+
+    server.registerTool(
+        'summarize',
+        { description: 'Summarize text using the host LLM', inputSchema: z.object({ text: z.string() }) },
+        async ({ text }, ctx): Promise<CallToolResult | InputRequiredResult> => {
+            const messages = [
+                {
+                    role: 'user' as const,
+                    content: { type: 'text' as const, text: `Please summarize the following text concisely:\n\n${text}` }
+                }
+            ];
+            if (reqCtx.era === 'legacy') {
+                // 2025-era: push a server→client `sampling/createMessage` request
+                // and await the model's answer in-line.
+                const response = await ctx.mcpReq.requestSampling({ messages, maxTokens: 500 });
+                // `content` is a single block when no tools were passed.
+                const content = response.content;
+                const summary = !Array.isArray(content) && content.type === 'text' ? content.text : 'Unable to generate summary';
+                return { content: [{ type: 'text', text: summary }] };
+            }
+            // 2026-07-28: return inputRequired with an embedded
+            // `sampling/createMessage` — the client's auto-fulfilment driver
+            // dispatches it to the same `sampling/createMessage` handler and
+            // retries this call with the model's response attached.
+            const response = ctx.mcpReq.inputResponses?.['summary'] as { content?: { type: string; text?: string } } | undefined;
+            if (!response) {
+                return inputRequired({
+                    inputRequests: { summary: inputRequired.createMessage({ messages, maxTokens: 500 }) }
+                });
+            }
+            const summary = response.content?.type === 'text' ? (response.content.text ?? '') : 'Unable to generate summary';
+            return { content: [{ type: 'text', text: summary }] };
+        }
+    );
+
+    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`);
+    });
+}