feat(agents): make @modelcontextprotocol/sdk and /server optional peers

.changeset/optional-mcp-server-peers.md

@@ -0,0 +1,5 @@
+---
+"agents": minor
+---
+
+`@modelcontextprotocol/sdk` and `@modelcontextprotocol/server` are now optional peer dependencies, so apps that do not serve MCP no longer install the SDK v1 server stack (`express`, `cors`, `@hono/node-server`, and others). Install `@modelcontextprotocol/server` for `agents/mcp/server`, and `@modelcontextprotocol/sdk` for `McpAgent`, `WorkerTransport`, `createLegacyMcpHandler`, and `agents/experimental/webmcp`. The root `agents` entry and `agents/mcp/client` need neither. If your app imports `@modelcontextprotocol/sdk` without listing it in `package.json`, add it before upgrading. The `agents/mcp` barrel needs `@modelcontextprotocol/sdk` even when you only import client helpers from it, so import those from `agents/mcp/client` instead. See [Creating MCP Servers](https://github.com/cloudflare/agents/blob/main/docs/agents/mcp-servers.md#choosing-an-approach).

docs/agents/mcp-client.md

@@ -63,6 +63,8 @@ Install the exact MCP client peer used by this Agents release:
 pnpm add agents @modelcontextprotocol/client@2.3.1
 ```
 
+The MCP client does not need `@modelcontextprotocol/sdk` or `@modelcontextprotocol/server`. Those packages are optional peers used only by the MCP server APIs.
+
 ```typescript
 import { Agent } from "agents";
 

docs/agents/mcp-servers.md

@@ -8,7 +8,7 @@ Build an MCP server on Workers with `createMcpHandler` from `agents/mcp/server`
 pnpm add agents @modelcontextprotocol/server@2.3.1 zod
 ```
 
-Use the exact `@modelcontextprotocol/server` version required by your installed Agents release.
+`@modelcontextprotocol/server` is an optional peer dependency of `agents`, so your package manager does not install it for you. Use the exact version required by your installed Agents release.
 
 ## Create a server
 

packages/agents/README.md

@@ -509,7 +509,8 @@ export default {
 } satisfies ExportedHandler;
 ```
 
-Install `@modelcontextprotocol/server` alongside `agents`. See
+Install `@modelcontextprotocol/server` alongside `agents`; it is an optional
+peer, so it is not installed for you. See
 [Creating MCP Servers](../../docs/agents/mcp-servers.md) for authentication,
 elicitation, and keeping state in bindings.
 

packages/agents/package.json

@@ -109,6 +109,12 @@
     "@earendil-works/pi-durable": {
       "optional": true
     },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "@modelcontextprotocol/server": {
+      "optional": true
+    },
     "@opencode/plugin": {
       "optional": true
     },

packages/agents/src/index.ts

@@ -163,9 +163,8 @@ import {
 } from "./observability/tracing/tracer";
 import { DisposableStore } from "./core/events";
 import { MessageType } from "./types";
-import { RPC_DO_PREFIX } from "./mcp/rpc";
+import { RPC_DO_PREFIX, type McpRpcAgent } from "./mcp/rpc";
 import { ensureMcpServerTable } from "./mcp/client/storage";
-import type { McpAgent } from "./mcp";
 import { Scheduler, setSchedulerCallbackResolver } from "./schedules/scheduler";
 import { Queue, setQueueCallbackResolver } from "./queue/queue";
 import type { QueueItem } from "./queue/types";
@@ -9426,7 +9425,7 @@ export class Agent<
   }
 
   private _findBindingNameForNamespace(
-    namespace: DurableObjectNamespace<McpAgent>
+    namespace: DurableObjectNamespace<McpRpcAgent>
   ): string | undefined {
     for (const [key, value] of Object.entries(
       this.env as Record<string, unknown>
@@ -9642,7 +9641,7 @@ export class Agent<
    * await this.addMcpServer("counter", env.MY_MCP);
    * await this.addMcpServer("counter", env.MY_MCP, { props: { userId: "123" } });
    */
-  async addMcpServer<T extends McpAgent>(
+  async addMcpServer<T extends McpRpcAgent>(
     serverName: string,
     binding: DurableObjectNamespace<T>,
     options?: AddRpcMcpServerOptions
@@ -9671,7 +9670,7 @@ export class Agent<
     | { id: string; state: typeof MCPConnectionState.READY }
   >;
 
-  async addMcpServer<T extends McpAgent>(
+  async addMcpServer<T extends McpRpcAgent>(
     serverName: string,
     urlOrBinding: string | DurableObjectNamespace<T>,
     callbackHostOrOptions?:
@@ -9833,7 +9832,7 @@ export class Agent<
           transport: {
             type: "rpc" as TransportType,
             namespace:
-              urlOrBinding as unknown as DurableObjectNamespace<McpAgent>,
+              urlOrBinding as unknown as DurableObjectNamespace<McpRpcAgent>,
             name: normalizedName,
             props: rpcOpts?.props
           }
@@ -9855,7 +9854,7 @@ export class Agent<
       }
 
       const bindingName = this._findBindingNameForNamespace(
-        urlOrBinding as unknown as DurableObjectNamespace<McpAgent>
+        urlOrBinding as unknown as DurableObjectNamespace<McpRpcAgent>
       );
       if (bindingName) {
         this.mcp.saveRpcServerToStorage(

packages/agents/src/mcp/client/index.ts

@@ -16,6 +16,17 @@ import type {
   Tool
 } from "@modelcontextprotocol/client";
 export type { ElicitRequest, ElicitResult } from "@modelcontextprotocol/client";
+export {
+  RPC_DO_PREFIX,
+  RPCClientTransport,
+  type McpRpcAgent,
+  type RPCClientTransportOptions
+} from "../rpc";
+export type {
+  MCPElicitationHandler,
+  MCPElicitationHandlers
+} from "./connection";
+export type { McpClientOptions } from "../types";
 import { type RetryOptions, tryN } from "../../retries";
 import { z } from "zod";
 import { nanoid } from "nanoid";

packages/agents/src/mcp/client/invoker-compat.ts

@@ -0,0 +1,86 @@
+import type {
+  CallToolRequest,
+  CallToolRequestOptions,
+  Client,
+  ListToolsResult
+} from "@modelcontextprotocol/client";
+import type { Client as LegacyClient } from "@modelcontextprotocol/sdk/client/index.js";
+import type {
+  CallToolResult as LegacyCallToolResult,
+  ListToolsRequest
+} from "@modelcontextprotocol/sdk/types.js";
+import type { RequestOptions as LegacyRequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import {
+  type CallToolSchemaOrOptions,
+  normalizeCallToolArguments
+} from "./invoker";
+
+// Accepts both SDK v1 and v2 clients. Kept separate from `./invoker` because
+// its types depend on `@modelcontextprotocol/sdk`, an optional peer that only
+// the x402 entry needs.
+
+export type CompatibleMcpClient = Client | LegacyClient;
+
+export interface BoundMcpClientInvoker {
+  listTools(
+    params?: ListToolsRequest["params"],
+    options?: CallToolRequestOptions
+  ): Promise<ListToolsResult>;
+  callTool(
+    params: CallToolRequest["params"],
+    schemaOrOptions?: CallToolSchemaOrOptions,
+    options?: CallToolRequestOptions
+  ): Promise<LegacyCallToolResult>;
+}
+
+/**
+ * Bind the original methods before decorators such as x402 replace them. All
+ * generation-specific calling conventions stay behind this small interface.
+ */
+export function bindMcpClient(
+  client: CompatibleMcpClient
+): BoundMcpClientInvoker {
+  const isV2 =
+    "getProtocolEra" in client &&
+    typeof (client as { getProtocolEra?: unknown }).getProtocolEra ===
+      "function";
+
+  if (isV2) {
+    const v2Client = client as Client;
+    const listTools = v2Client.listTools.bind(v2Client);
+    const callTool = v2Client.callTool.bind(v2Client);
+    return {
+      listTools: (params, options) => listTools(params, options),
+      callTool: (params, schemaOrOptions, options) => {
+        const normalized = normalizeCallToolArguments(schemaOrOptions, options);
+        const pending = normalized.schema
+          ? v2Client.request(
+              { method: "tools/call", params },
+              normalized.schema as never,
+              normalized.options
+            )
+          : callTool(params, normalized.options);
+        return pending as Promise<LegacyCallToolResult>;
+      }
+    };
+  }
+
+  const legacy = client as LegacyClient;
+  const listTools = legacy.listTools.bind(legacy);
+  const callTool = legacy.callTool.bind(legacy);
+  return {
+    listTools: (params, options) =>
+      listTools(
+        params,
+        options as LegacyRequestOptions
+      ) as Promise<ListToolsResult>,
+    callTool: (params, schemaOrOptions, options) => {
+      const normalized = normalizeCallToolArguments(schemaOrOptions, options);
+      return callTool(
+        params as Parameters<LegacyClient["callTool"]>[0],
+        normalized.schema as Parameters<LegacyClient["callTool"]>[1],
+        normalized.options as LegacyRequestOptions
+      ) as Promise<LegacyCallToolResult>;
+    }
+  };
+}

packages/agents/src/mcp/client/invoker.ts

@@ -2,40 +2,25 @@ import type {
   CallToolRequest,
   CallToolRequestOptions,
   CallToolResult,
-  Client,
-  ListToolsResult
+  Client
 } from "@modelcontextprotocol/client";
-import type { Client as LegacyClient } from "@modelcontextprotocol/sdk/client/index.js";
-import type {
-  CallToolResult as LegacyCallToolResult,
-  CallToolResultSchema,
-  CompatibilityCallToolResultSchema,
-  ListToolsRequest
-} from "@modelcontextprotocol/sdk/types.js";
-import type { RequestOptions as LegacyRequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js";
 
-export type LegacyCallToolResultSchema =
-  | typeof CallToolResultSchema
-  | typeof CompatibilityCallToolResultSchema;
+/**
+ * A v1 result schema such as `CallToolResultSchema` or
+ * `CompatibilityCallToolResultSchema` from `@modelcontextprotocol/sdk`.
+ *
+ * Typed structurally so the MCP client (reachable from the root `agents`
+ * entry) does not depend on `@modelcontextprotocol/sdk`, which is an optional
+ * peer.
+ */
+export type LegacyCallToolResultSchema = {
+  parse(data: unknown): unknown;
+};
 
 export type CallToolSchemaOrOptions =
   | LegacyCallToolResultSchema
   | CallToolRequestOptions;
 
-export type CompatibleMcpClient = Client | LegacyClient;
-
-export interface BoundMcpClientInvoker {
-  listTools(
-    params?: ListToolsRequest["params"],
-    options?: CallToolRequestOptions
-  ): Promise<ListToolsResult>;
-  callTool(
-    params: CallToolRequest["params"],
-    schemaOrOptions?: CallToolSchemaOrOptions,
-    options?: CallToolRequestOptions
-  ): Promise<LegacyCallToolResult>;
-}
-
 function isLegacyResultSchema(
   value: CallToolSchemaOrOptions | undefined
 ): value is LegacyCallToolResultSchema {
@@ -44,7 +29,7 @@ function isLegacyResultSchema(
   );
 }
 
-function normalizeCallToolArguments(
+export function normalizeCallToolArguments(
   schemaOrOptions?: CallToolSchemaOrOptions,
   options?: CallToolRequestOptions
 ): {
@@ -76,55 +61,3 @@ export function callV2Tool(
   }
   return client.callTool(params, normalized.options);
 }
-
-/**
- * Bind the original methods before decorators such as x402 replace them. All
- * generation-specific calling conventions stay behind this small interface.
- */
-export function bindMcpClient(
-  client: CompatibleMcpClient
-): BoundMcpClientInvoker {
-  const isV2 =
-    "getProtocolEra" in client &&
-    typeof (client as { getProtocolEra?: unknown }).getProtocolEra ===
-      "function";
-
-  if (isV2) {
-    const v2Client = client as Client;
-    const listTools = v2Client.listTools.bind(v2Client);
-    const callTool = v2Client.callTool.bind(v2Client);
-    return {
-      listTools: (params, options) => listTools(params, options),
-      callTool: (params, schemaOrOptions, options) => {
-        const normalized = normalizeCallToolArguments(schemaOrOptions, options);
-        const pending = normalized.schema
-          ? v2Client.request(
-              { method: "tools/call", params },
-              normalized.schema as never,
-              normalized.options
-            )
-          : callTool(params, normalized.options);
-        return pending as Promise<LegacyCallToolResult>;
-      }
-    };
-  }
-
-  const legacy = client as LegacyClient;
-  const listTools = legacy.listTools.bind(legacy);
-  const callTool = legacy.callTool.bind(legacy);
-  return {
-    listTools: (params, options) =>
-      listTools(
-        params,
-        options as LegacyRequestOptions
-      ) as Promise<ListToolsResult>,
-    callTool: (params, schemaOrOptions, options) => {
-      const normalized = normalizeCallToolArguments(schemaOrOptions, options);
-      return callTool(
-        params as Parameters<LegacyClient["callTool"]>[0],
-        normalized.schema,
-        normalized.options as LegacyRequestOptions
-      ) as Promise<LegacyCallToolResult>;
-    }
-  };
-}

packages/agents/src/mcp/client/x402.ts

@@ -26,12 +26,11 @@ import type {
   CallToolResult,
   ToolAnnotations
 } from "@modelcontextprotocol/sdk/types.js";
-import {
-  bindMcpClient,
-  type CallToolSchemaOrOptions,
-  type CompatibleMcpClient,
-  type LegacyCallToolResultSchema
+import type {
+  CallToolSchemaOrOptions,
+  LegacyCallToolResultSchema
 } from "./invoker";
+import { bindMcpClient, type CompatibleMcpClient } from "./invoker-compat";
 import type { z, ZodRawShape } from "zod";
 
 // v2 imports from @x402/core