From a01872d8c526085f0fd3b170e5fcb5fe7f90f1a8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 25 Nov 2025 15:16:58 +0000 Subject: [PATCH] Update MCP Server API documentation for SDK v1.22.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This updates all MCP server examples to use the new registerTool API from @modelcontextprotocol/sdk v1.22.0, which introduces a breaking change to the tool registration syntax. Changes: - Replace server.tool() with server.registerTool() - Update tool registration to use object-based configuration with description and inputSchema properties - Update examples across all MCP-related documentation pages The new API improves clarity by explicitly separating the tool description and input schema into a configuration object. Synced from cloudflare/agents PR #659 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../model-context-protocol/authorization.mdx | 44 +++++++++---- .../model-context-protocol/mcp-agent-api.mdx | 15 +++-- .../mcp-handler-api.mdx | 64 +++++++++++-------- .../agents/model-context-protocol/tools.mdx | 7 +- src/content/docs/agents/x402.mdx | 8 ++- 5 files changed, 91 insertions(+), 47 deletions(-) diff --git a/src/content/docs/agents/model-context-protocol/authorization.mdx b/src/content/docs/agents/model-context-protocol/authorization.mdx index 9fe05a65768..c52dd48047e 100644 --- a/src/content/docs/agents/model-context-protocol/authorization.mdx +++ b/src/content/docs/agents/model-context-protocol/authorization.mdx @@ -182,9 +182,15 @@ When a user authenticates to your MCP server through Cloudflare's OAuth Provider ```js export class MyMCP extends McpAgent { async init() { - this.server.tool("userInfo", "Get user information", {}, async () => ({ - content: [{ type: "text", text: `Hello, ${this.props.claims.name || "user"}!` }], - })); + this.server.registerTool( + "userInfo", + { + description: "Get user information" + }, + async () => ({ + content: [{ type: "text", text: `Hello, ${this.props.claims.name || "user"}!` }], + }) + ); } } ``` @@ -222,15 +228,23 @@ function requirePermission(permission, handler) { // Use the wrapper with your MCP tools async init() { // Basic tools available to all authenticated users - this.server.tool("basicTool", "Available to all users", {}, async () => { - // Implementation for all users - }); + this.server.registerTool( + "basicTool", + { + description: "Available to all users" + }, + async () => { + // Implementation for all users + } + ); // Protected tool using the permission wrapper - this.server.tool( + this.server.registerTool( "adminAction", - "Administrative action requiring special permission", - { /* parameters */ }, + { + description: "Administrative action requiring special permission" + // inputSchema can include parameters if needed + }, requirePermission("admin", async (req) => { // Only executes if user has "admin" permission return { @@ -241,9 +255,15 @@ async init() { // Conditionally register tools based on user permissions if (this.props.permissions?.includes("special_feature")) { - this.server.tool("specialTool", "Special feature", {}, async () => { - // This tool only appears for users with the special_feature permission - }); + this.server.registerTool( + "specialTool", + { + description: "Special feature" + }, + async () => { + // This tool only appears for users with the special_feature permission + } + ); } } ``` diff --git a/src/content/docs/agents/model-context-protocol/mcp-agent-api.mdx b/src/content/docs/agents/model-context-protocol/mcp-agent-api.mdx index cbfd64c8dc3..82f7c8174a2 100644 --- a/src/content/docs/agents/model-context-protocol/mcp-agent-api.mdx +++ b/src/content/docs/agents/model-context-protocol/mcp-agent-api.mdx @@ -22,9 +22,12 @@ export class MyMCP extends McpAgent { server = new McpServer({ name: "Demo", version: "1.0.0" }); async init() { - this.server.tool( + this.server.registerTool( "add", - { a: z.number(), b: z.number() }, + { + description: "Adds two numbers together", + inputSchema: { a: z.number(), b: z.number() } + }, async ({ a, b }) => ({ content: [{ type: "text", text: String(a + b) }], }), @@ -106,10 +109,12 @@ export class MyMCP extends McpAgent { }; }); - this.server.tool( + this.server.registerTool( "add", - "Add to the counter, stored in the MCP", - { a: z.number() }, + { + description: "Add to the counter, stored in the MCP", + inputSchema: { a: z.number() } + }, async ({ a }) => { this.setState({ ...this.state, counter: this.state.counter + a }); diff --git a/src/content/docs/agents/model-context-protocol/mcp-handler-api.mdx b/src/content/docs/agents/model-context-protocol/mcp-handler-api.mdx index 6a58630e0e2..a41bac8004f 100644 --- a/src/content/docs/agents/model-context-protocol/mcp-handler-api.mdx +++ b/src/content/docs/agents/model-context-protocol/mcp-handler-api.mdx @@ -128,10 +128,12 @@ const server = new McpServer({ version: "1.0.0", }); -server.tool( +server.registerTool( "hello", - "Returns a greeting message", - { name: z.string().optional() }, + { + description: "Returns a greeting message", + inputSchema: { name: z.string().optional() } + }, async ({ name }) => { return { content: [ @@ -437,21 +439,27 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; const server = new McpServer({ name: "Auth Server", version: "1.0.0" }); -server.tool("getProfile", "Get the current user's profile", {}, async () => { - // Access user info automatically populated by OAuth provider - const auth = getMcpAuthContext(); - const username = auth?.props?.username as string | undefined; - const email = auth?.props?.email as string | undefined; - - return { - content: [ - { - type: "text", - text: `User: ${username ?? "anonymous"}, Email: ${email ?? "none"}`, - }, - ], - }; -}); +server.registerTool( + "getProfile", + { + description: "Get the current user's profile" + }, + async () => { + // Access user info automatically populated by OAuth provider + const auth = getMcpAuthContext(); + const username = auth?.props?.username as string | undefined; + const email = auth?.props?.email as string | undefined; + + return { + content: [ + { + type: "text", + text: `User: ${username ?? "anonymous"}, Email: ${email ?? "none"}`, + }, + ], + }; + } +); ``` @@ -467,14 +475,20 @@ The `createMcpHandler` automatically catches errors and returns JSON-RPC error r ```ts -server.tool("riskyOperation", "An operation that might fail", {}, async () => { - if (Math.random() > 0.5) { - throw new Error("Random failure occurred"); +server.registerTool( + "riskyOperation", + { + description: "An operation that might fail" + }, + async () => { + if (Math.random() > 0.5) { + throw new Error("Random failure occurred"); + } + return { + content: [{ type: "text", text: "Success!" }], + }; } - return { - content: [{ type: "text", text: "Success!" }], - }; -}); +); // Errors are automatically caught and returned as: // { diff --git a/src/content/docs/agents/model-context-protocol/tools.mdx b/src/content/docs/agents/model-context-protocol/tools.mdx index fc9bc55c884..3697425144e 100644 --- a/src/content/docs/agents/model-context-protocol/tools.mdx +++ b/src/content/docs/agents/model-context-protocol/tools.mdx @@ -22,9 +22,12 @@ import { z } from "zod"; export class MyMCP extends McpAgent { server = new McpServer({ name: "Demo", version: "1.0.0" }); async init() { - this.server.tool( + this.server.registerTool( "add", - { a: z.number(), b: z.number() }, + { + description: "Adds two numbers together", + inputSchema: { a: z.number(), b: z.number() } + }, async ({ a, b }) => ({ content: [{ type: "text", text: String(a + b) }], }), diff --git a/src/content/docs/agents/x402.mdx b/src/content/docs/agents/x402.mdx index 0e43634458d..34da2447d7b 100644 --- a/src/content/docs/agents/x402.mdx +++ b/src/content/docs/agents/x402.mdx @@ -125,10 +125,12 @@ export class PaidMCP extends McpAgent { ); // Free tool - this.server.tool( + this.server.registerTool( "echo", - "Echo a message", - { message: z.string() }, + { + description: "Echo a message", + inputSchema: { message: z.string() } + }, async ({ message }) => { return { content: [{ type: "text", text: message }] }; },