Exact @modelcontextprotocol/* peer pins block MCP SDK 1.30.1 / server 2.1.0

[awhitford]

Version

agents@0.24.0 (latest)

Summary

agents pins its three MCP peers to exact versions:

"peerDependencies": {
  "@modelcontextprotocol/client": "2.0.0",
  "@modelcontextprotocol/sdk": "1.30.0",
  "@modelcontextprotocol/server": "2.0.0"
}

Every other peer in the same block uses a range (ai: ^6.0.0 || ^7.0.0, zod: ^4.0.0, react: ^19.0.0, vite: >=6.0.0 <9.0.0), and the same exact versions appear in devDependencies, so this reads as a deliberate lockstep rather than an oversight.

The consequence is that a consumer cannot take any MCP SDK release until agents cuts a matching one. The typescript-sdk published 1.30.1 and @modelcontextprotocol/server 2.1.0 on 2026-09-23, five days after agents@0.24.0 (2026-09-18), and there is no newer agents release — so today the latest agents and the latest MCP SDK cannot be installed together cleanly.

Repro

With agents@0.24.0 installed and the MCP packages updated to latest:

✕ unmet peer @modelcontextprotocol/sdk
  Installed: 1.30.1
  Wanted:
    1.30.0:
      agents@0.24.0

✕ unmet peer @modelcontextprotocol/server
  Installed: 2.1.0
  Wanted:
    2.0.0:
      agents@0.24.0

Why this is more than a warning

A transitive dependency with its own caret range on @modelcontextprotocol/sdk resolves a second copy next to the pinned one. Two copies are not merely wasteful: the SDK's types become structurally distinct, so an McpServer built from one is not assignable to a handler expecting the other, and tsc fails:

error TS2345: Argument of type
  '…/@modelcontextprotocol+sdk@1.30.0/…/server/mcp").McpServer' is not assignable to parameter of type
  '…/@modelcontextprotocol+sdk@1.30.1/…/server/mcp").McpServer'.

Worth noting our test suite passed with both copies present — only the typecheck caught it. So the exact pin does not merely warn; combined with any dependency that ranges on the SDK, it can produce a broken build that runtime tests do not surface.

Workaround for anyone hitting this: pin the MCP packages to the versions agents wants and add a package-manager override to force a single copy.

Ask

Either of these would unblock consumers:

1. Release a bump tracking @modelcontextprotocol/sdk@1.30.1 / server@2.1.0 / client@2.1.0.
2. Widen the peer ranges, at least to allow patch releases (~1.30.0) or minors (^1.30.0), so a consumer can take a security or bug-fix patch without waiting for an agents release.

If the exact pin is load-bearing — the SDK's internals being reached into, say — then saying so in the README would help, since the contrast with the ranged peers beside it reads as accidental from the outside.

Note on scope

To be precise about what is and isn't established here: I did not test agents@0.24.0 against sdk 1.30.1 / server 2.1.0 at runtime — I held our dependencies back at the pinned versions instead. The claim is that the declared peer range blocks adoption and produces the duplicate-copy build failure above, not that the newer SDK is actually incompatible. It may well work fine.

[Kin230k]

The safest contract here seems to be “one MCP type universe per consumer,” not merely “our own tests pass.” A useful regression would install the packed agents tarball into a tiny external fixture twice: once at the declared lower bounds and once at the newest versions allowed by the intended ranges. The fixture should import McpServer from the consumer's SDK, pass it through the public agents/mcp surface, and run the package manager's strict peer check plus tsc --noEmit. That catches the duplicate-copy/type-identity failure that the current runtime suite misses.

If 1.x SDK patches and 2.x client/server minors are intended to be compatible, ^1.30.0 and ^2.0.0 express that policy and the “latest allowed” fixture makes widening measurable rather than optimistic. If exact lockstep is intentional, I would keep the pins but add an automated release gate that detects a newer MCP release and either opens an aligned version bump or records the incompatibility rationale. Either route makes the support boundary explicit; the current exact peers silently turn release cadence into a consumer build constraint.

[DeepanshuPal]

I reproduced the MCP peer conflict and prepared a fix that widens the peer ranges, with a changeset and a packed external-consumer regression: https://github.com/DeepanshuPal/cloudflare-agents/tree/fix/2376-mcp-peer-ranges

The Node tests passed 21/21, the package build passed, and strict installs and TypeScript checks passed for consumers using the pinned versions and SDK 1.30.1 / client and server 2.1.0. The full monorepo check did not finish, so CI is still needed.

GitHub currently limits PR creation here to collaborators. If access is available, I'm happy to open the PR; otherwise a maintainer is welcome to use the patch from that branch.

[awhitford]

Note that @modelcontextprotocol/sdk 1.31.0 and @modelcontextprotocol/server 2.2.0 are now available.