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:
+
+<PackageManagers pkg="agents @modelcontextprotocol/sdk@1.32.1 zod" />
+
 <TypeScriptExample>
 
 ```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:
 
-<PackageManagers pkg="agents @modelcontextprotocol/server@2.0.0 zod" />
+<PackageManagers pkg="agents @modelcontextprotocol/server@2.3.1 zod" />
 
 For an explicit legacy server:
 
-<PackageManagers pkg="agents @modelcontextprotocol/sdk@1.30.0 zod" />
+<PackageManagers pkg="agents @modelcontextprotocol/sdk@1.32.1 zod" />
 
 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:
 
-<PackageManagers pkg="agents @modelcontextprotocol/server@2.0.0 zod" />
+<PackageManagers pkg="agents @modelcontextprotocol/server@2.3.1 zod" />
 
 For a temporary legacy lane:
 
-<PackageManagers pkg="agents @modelcontextprotocol/sdk@1.30.0 zod" />
+<PackageManagers pkg="agents @modelcontextprotocol/sdk@1.32.1 zod" />
 
 For an Agent that connects to MCP servers:
 
-<PackageManagers pkg="agents @modelcontextprotocol/client@2.0.0" />
+<PackageManagers pkg="agents @modelcontextprotocol/client@2.3.1" />
 
-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:
 
 <TypeScriptExample>