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

@@ -0,0 +1,8 @@
+# tools
+
+**Start here.** Register tools with `McpServer.registerTool`; the SDK infers the JSON Schema from any Standard-Schema-compatible input (Zod here) and emits `structuredContent` matching `outputSchema`. The client lists tools, inspects schemas and `annotations`, calls them, and
+asserts structured output.
+
+```bash
+pnpm tsx examples/tools/client.ts
+```

examples/tools/client.ts

@@ -0,0 +1,49 @@
+/**
+ * Drives the tools example: list, inspect schemas + annotations, call,
+ * assert structured output, assert an unknown tool errors.
+ */
+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: 'tools-example-client', version: '1.0.0' },
+    { versionNegotiation: { mode: era === 'modern' ? 'auto' : 'legacy' } }
+);
+
+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))));
+
+const list = await client.listTools();
+const names = new Set(list.tools.map(t => t.name));
+check.ok(names.has('calc') && names.has('echo'), 'tools/list should contain calc and echo');
+
+const calc = list.tools.find(t => t.name === 'calc')!;
+check.equal(calc.annotations?.readOnlyHint, true);
+const required = (calc.inputSchema as { required?: string[] }).required ?? [];
+check.ok(required.includes('op') && required.includes('a') && required.includes('b'));
+check.ok(calc.outputSchema, 'calc should publish an outputSchema');
+check.equal(calc.icons?.[0]?.src, 'https://example.test/calc.svg', 'calc should advertise its icons over the wire');
+
+const result = await client.callTool({ name: 'calc', arguments: { op: 'add', a: 2, b: 3 } });
+check.equal((result.structuredContent as { result?: number } | undefined)?.result, 5);
+check.equal((result.structuredContent as { op?: string } | undefined)?.op, 'add');
+
+const echo = await client.callTool({ name: 'echo', arguments: { text: 'hi' } });
+check.equal(echo.content?.[0]?.type === 'text' ? echo.content[0].text : '', 'hi');
+check.equal(echo.structuredContent, undefined);
+
+// An unknown tool should be a tool error (isError) or a wire error — either is acceptable.
+let unknownFailed = false;
+try {
+    const r = await client.callTool({ name: 'nope', arguments: {} });
+    unknownFailed = !!r.isError;
+} catch {
+    unknownFailed = true;
+}
+check.ok(unknownFailed, 'calling an unknown tool should fail');
+
+await client.close();

examples/tools/package.json

@@ -0,0 +1,19 @@
+{
+    "name": "@mcp-examples/tools",
+    "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"
+    }
+}

examples/tools/server.ts

@@ -0,0 +1,65 @@
+/**
+ * Tools primitive — start here.
+ *
+ * Register tools with `McpServer.registerTool`: typed input via any
+ * Standard-Schema-with-JSON library (Zod here), inferred output schema +
+ * `structuredContent` from `outputSchema`, `annotations` for behavioral hints
+ * (`readOnlyHint`, `destructiveHint`). One binary, either transport.
+ */
+import { createServer } from 'node:http';
+
+import { parseExampleArgs } from '@mcp-examples/shared';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+import type { CallToolResult } from '@modelcontextprotocol/server';
+import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
+import { serveStdio } from '@modelcontextprotocol/server/stdio';
+import * as z from 'zod/v4';
+
+function buildServer(): McpServer {
+    const server = new McpServer({ name: 'tools-example', version: '1.0.0' });
+
+    // A read-only tool with typed input and inferred structured output.
+    server.registerTool(
+        'calc',
+        {
+            title: 'Calculator',
+            description: 'Apply an arithmetic operation to two numbers',
+            inputSchema: z.object({
+                op: z.enum(['add', 'sub', 'mul']).describe('the operation to apply'),
+                a: z.number().describe('left operand'),
+                b: z.number().describe('right operand')
+            }),
+            outputSchema: z.object({ op: z.string(), result: z.number() }),
+            annotations: { readOnlyHint: true, idempotentHint: true },
+            // Icons a client may render in its UI. `src` is required;
+            // `mimeType`, `sizes`, and `theme` are optional hints.
+            icons: [{ src: 'https://example.test/calc.svg', mimeType: 'image/svg+xml', sizes: ['any'] }]
+        },
+        async ({ op, a, b }) => {
+            const result = op === 'add' ? a + b : op === 'sub' ? a - b : a * b;
+            const structuredContent = { op, result };
+            return { content: [{ type: 'text', text: `${a} ${op} ${b} = ${result}` }], structuredContent };
+        }
+    );
+
+    // A plain string-returning tool (no structuredContent).
+    server.registerTool(
+        'echo',
+        { description: 'Echoes the input', inputSchema: z.object({ text: z.string() }) },
+        async ({ text }): Promise<CallToolResult> => ({ content: [{ type: 'text', text }] })
+    );
+
+    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`);
+    });
+}