From 821129f9bb2feab123face9a51a63c2b2361964b Mon Sep 17 00:00:00 2001 From: Matt Carey Date: Tue, 20 Oct 2026 23:39:48 +0100 Subject: [PATCH] [Agents] MCP server SDK packages are optional peers --- .../agents/model-context-protocol/apis/agent-api.mdx | 6 +++++- .../agents/model-context-protocol/apis/client-api.mdx | 2 +- .../agents/model-context-protocol/apis/handler-api.mdx | 6 ++++-- .../guides/migrate-to-mcp-sdk-v2.mdx | 10 ++++++---- .../model-context-protocol/protocol/transport.mdx | 2 ++ 5 files changed, 18 insertions(+), 8 deletions(-) diff --git a/src/content/docs/agents/model-context-protocol/apis/agent-api.mdx b/src/content/docs/agents/model-context-protocol/apis/agent-api.mdx index 9f140b05109..9b4f2ad45ed 100644 --- a/src/content/docs/agents/model-context-protocol/apis/agent-api.mdx +++ b/src/content/docs/agents/model-context-protocol/apis/agent-api.mdx @@ -10,7 +10,7 @@ products: - agents --- -import { TypeScriptExample, LinkCard } from "~/components"; +import { TypeScriptExample, LinkCard, PackageManagers } from "~/components"; `McpAgent` creates a stateful legacy MCP server backed by a Durable Object. @@ -26,6 +26,10 @@ Refer to [Migrate to MCP SDK v2](/agents/model-context-protocol/guides/migrate-t ::: +`McpAgent` requires `@modelcontextprotocol/sdk`, which is an optional peer dependency of `agents`. Install the exact version used by your Agents release: + + + ```ts title="src/index.ts" diff --git a/src/content/docs/agents/model-context-protocol/apis/client-api.mdx b/src/content/docs/agents/model-context-protocol/apis/client-api.mdx index 2b061bc435e..dfb205957fc 100644 --- a/src/content/docs/agents/model-context-protocol/apis/client-api.mdx +++ b/src/content/docs/agents/model-context-protocol/apis/client-api.mdx @@ -12,7 +12,7 @@ products: import { Render, TypeScriptExample, LinkCard } from "~/components"; -Connect your agent to external [Model Context Protocol (MCP)](/agents/model-context-protocol/) servers to use their tools, resources, and prompts. Agents SDK v0.20.0 uses `@modelcontextprotocol/client` and negotiates stateless or legacy behavior automatically. +Connect your agent to external [Model Context Protocol (MCP)](/agents/model-context-protocol/) servers to use their tools, resources, and prompts. Agents SDK v0.20.0 uses `@modelcontextprotocol/client` and negotiates stateless or legacy behavior automatically. The MCP client does not need `@modelcontextprotocol/sdk` or `@modelcontextprotocol/server`. Refer to [Migrate to MCP SDK v2](/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2/) for package, type, OAuth provider, and rollout changes. diff --git a/src/content/docs/agents/model-context-protocol/apis/handler-api.mdx b/src/content/docs/agents/model-context-protocol/apis/handler-api.mdx index 7a482f3e316..76157eb891b 100644 --- a/src/content/docs/agents/model-context-protocol/apis/handler-api.mdx +++ b/src/content/docs/agents/model-context-protocol/apis/handler-api.mdx @@ -23,13 +23,15 @@ The Agents SDK provides two server handler paths: ## Install dependencies +`@modelcontextprotocol/server` and `@modelcontextprotocol/sdk` are optional peer dependencies of `agents`. Your package manager does not install them for you, so add the one your server uses. + For a stateless server: - + For an explicit legacy server: - + Use the exact MCP versions required by your installed Agents release. diff --git a/src/content/docs/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2.mdx b/src/content/docs/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2.mdx index aeef6601a16..a105a5dad73 100644 --- a/src/content/docs/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2.mdx +++ b/src/content/docs/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2.mdx @@ -37,17 +37,19 @@ Install only the MCP package generations that your application imports. Keep the For a stateless server: - + For a temporary legacy lane: - + For an Agent that connects to MCP servers: - + -Follow peer dependency instructions from your package manager. Update the exact MCP versions with the Agents release that supports them. +`@modelcontextprotocol/server` and `@modelcontextprotocol/sdk` are optional peer dependencies of `agents`, so your package manager does not install them automatically. Add them to your own `package.json` when you use them. `@modelcontextprotocol/client` is a required peer, because every Agent includes the MCP client. Update the exact MCP versions with the Agents release that supports them. + +If an existing legacy server imports `@modelcontextprotocol/sdk` without listing it in `package.json`, it worked only because the package was installed as a dependency of `agents`. Add it explicitly before you upgrade. ## Decide whether a temporary legacy lane is required diff --git a/src/content/docs/agents/model-context-protocol/protocol/transport.mdx b/src/content/docs/agents/model-context-protocol/protocol/transport.mdx index 05ea1fc93a0..cc478c1163e 100644 --- a/src/content/docs/agents/model-context-protocol/protocol/transport.mdx +++ b/src/content/docs/agents/model-context-protocol/protocol/transport.mdx @@ -119,6 +119,8 @@ This section applies only to existing `McpAgent` deployments during migration. D #### 1. Define your MCP server +The `McpAgent` server requires `@modelcontextprotocol/sdk`. An Agent that only connects to it as a client does not. + Create your `McpAgent` with the tools you want to expose: