Skip to content

[Agents] MCP server SDK packages are optional peers #34485

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
mattzcarey wants to merge 1 commit into
base: production
Choose a base branch
from
+18 −8
Draft

[Agents] MCP server SDK packages are optional peers #34485

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion src/content/docs/agents/model-context-protocol/apis/agent-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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"
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/agents/model-context-protocol/apis/client-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
6 changes: 4 additions & 2 deletions src/content/docs/agents/model-context-protocol/apis/handler-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
10 changes: 6 additions & 4 deletions src/content/docs/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 2 additions & 0 deletions src/content/docs/agents/model-context-protocol/protocol/transport.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down
Loading