mattzcarey · Oct 27, 2026 · Oct 27, 2026 · devin-ai-integration · Oct 27, 2026
diff --git a/.changeset/mcp-sdk-2-4-cimd.md b/.changeset/mcp-sdk-2-4-cimd.md
@@ -0,0 +1,5 @@
+---
+"agents": patch
+---
+
+Update `@modelcontextprotocol/client` and `@modelcontextprotocol/server` to 2.4.0 and `@modelcontextprotocol/sdk` to 1.32.2, and add a `clientMetadataUrl` option to `DurableObjectOAuthClientProvider` for OAuth Client ID Metadata Documents. See [MCP client](https://developers.cloudflare.com/agents/model-context-protocol/apis/client-api/).
diff --git a/docs/agents/mcp-client.md b/docs/agents/mcp-client.md
@@ -60,7 +60,7 @@ available.
 Install the exact MCP client peer used by this Agents release:
 
 ```sh
-pnpm add agents @modelcontextprotocol/client@2.3.1
+pnpm add agents @modelcontextprotocol/client@2.4.0
 ```
 
 The MCP client does not need `@modelcontextprotocol/sdk` or `@modelcontextprotocol/server`. Those packages are optional peers used only by the MCP server APIs.
@@ -367,6 +367,28 @@ class MyAgent extends Agent {
 }
 ```
 
+#### Client ID Metadata Documents
+
+Some authorization servers accept a [Client ID Metadata Document](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#client-id-metadata-documents) instead of dynamic client registration. Pass `clientMetadataUrl` to use one. When a server advertises `client_id_metadata_document_supported`, the agent sends that URL as its `client_id`. Servers that don't advertise it still get dynamic client registration.
+
+```typescript
+import { Agent, DurableObjectOAuthClientProvider } from "agents";
+import type { AgentMcpOAuthProvider } from "agents";
+
+class MyAgent extends Agent {
+  createMcpOAuthProvider(callbackUrl: string): AgentMcpOAuthProvider {
+    return new DurableObjectOAuthClientProvider(
+      this.ctx.storage,
+      this.name,
+      callbackUrl,
+      { clientMetadataUrl: "https://my-app.example.com/oauth/client.json" }
+    );
+  }
+}
+```
+
+Serve the document at that URL. `provider.clientMetadataDocument` returns its JSON: `client_id` is the URL and `redirect_uris` holds the callback URL. The authorization server checks every redirect URI against the document, so pass a fixed `callbackPath` to `addMcpServer` rather than relying on the per-instance default.
+
 ## Using MCP Capabilities
 
 Once connected, access the server's capabilities:

diff --git a/docs/agents/mcp-servers.md b/docs/agents/mcp-servers.md
@@ -5,7 +5,7 @@ Build an MCP server on Workers with `createMcpHandler` from `agents/mcp/server`
 ## Install
 
 ```sh
-pnpm add agents @modelcontextprotocol/server@2.3.1 zod
+pnpm add agents @modelcontextprotocol/server@2.4.0 zod
 ```
 
 `@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.
@@ -279,7 +279,7 @@ If the handler lifecycle does not fit, use the SDK's `WebStandardStreamableHTTPS
 `McpAgent` is deprecated, but existing servers keep working. It is built on MCP SDK v1, which is an optional peer dependency of `agents`, so your package manager no longer installs it for you. Add the exact version your Agents release expects before you upgrade:
 
 ```sh
-pnpm add agents @modelcontextprotocol/sdk@1.32.1 zod
+pnpm add agents @modelcontextprotocol/sdk@1.32.2 zod
 ```
 
 Keep importing `McpServer` from `@modelcontextprotocol/sdk/server/mcp.js` in an `McpAgent`. An SDK v2 server from `@modelcontextprotocol/server` cannot run inside `McpAgent`. The same applies to `WorkerTransport` and `createLegacyMcpHandler` from `agents/mcp`.

diff --git a/examples/assistant/package.json b/examples/assistant/package.json
@@ -15,7 +15,7 @@
     "@cloudflare/computer": "^0.8.0",
     "@cloudflare/kumo": "^2.6.0",
     "@cloudflare/think": "*",
-    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "@phosphor-icons/react": "^2.1.10",
     "@streamdown/code": "^1.1.1",
     "agents": "*",

diff --git a/examples/codemode-connectors/package.json b/examples/codemode-connectors/package.json
@@ -12,7 +12,7 @@
     "@cloudflare/ai-chat": "*",
     "@cloudflare/codemode": "*",
     "@cloudflare/kumo": "^2.6.0",
-    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "@phosphor-icons/react": "^2.1.10",
     "@streamdown/code": "^1.1.1",
     "agents": "*",

diff --git a/examples/codemode-mcp-openapi/package.json b/examples/codemode-mcp-openapi/package.json
@@ -10,8 +10,8 @@
   },
   "dependencies": {
     "@cloudflare/codemode": "*",
-    "@modelcontextprotocol/sdk": "1.32.1",
-    "@modelcontextprotocol/server": "2.3.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@modelcontextprotocol/server": "2.4.0",
     "agents": "*"
   },
   "devDependencies": {

diff --git a/examples/codemode-mcp/package.json b/examples/codemode-mcp/package.json
@@ -10,8 +10,8 @@
   },
   "dependencies": {
     "@cloudflare/codemode": "*",
-    "@modelcontextprotocol/sdk": "1.32.1",
-    "@modelcontextprotocol/server": "2.3.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@modelcontextprotocol/server": "2.4.0",
     "agents": "*",
     "zod": "^4.6.7"
   },

diff --git a/examples/mcp-elicitation-mrtr/package.json b/examples/mcp-elicitation-mrtr/package.json
@@ -11,7 +11,7 @@
     "types": "wrangler types env.d.ts --include-runtime false"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "2.3.1",
+    "@modelcontextprotocol/server": "2.4.0",
     "agents": "*",
     "zod": "^4.6.7"
   },

diff --git a/examples/mcp-elicitation/package.json b/examples/mcp-elicitation/package.json
@@ -11,7 +11,7 @@
   },
   "type": "module",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "agents": "*",
     "zod": "^4.6.7"
   }

diff --git a/examples/mcp-rpc-transport/package.json b/examples/mcp-rpc-transport/package.json
@@ -11,7 +11,7 @@
   "dependencies": {
     "@cloudflare/ai-chat": "*",
     "@cloudflare/kumo": "^2.6.0",
-    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "@phosphor-icons/react": "^2.1.10",
     "agents": "*",
     "ai": "^7.0.0",

diff --git a/examples/mcp-server/package.json b/examples/mcp-server/package.json
@@ -10,7 +10,7 @@
     "types": "wrangler types env.d.ts --include-runtime false"
   },
   "dependencies": {
-    "@modelcontextprotocol/server": "2.3.1",
+    "@modelcontextprotocol/server": "2.4.0",
     "zod": "^4.6.7"
   },
   "devDependencies": {

diff --git a/examples/mcp-worker-authenticated/package.json b/examples/mcp-worker-authenticated/package.json
@@ -11,8 +11,8 @@
   "dependencies": {
     "@cloudflare/kumo": "^2.6.0",
     "@cloudflare/workers-oauth-provider": "^1.2.4",
-    "@modelcontextprotocol/sdk": "1.32.1",
-    "@modelcontextprotocol/server": "2.3.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@modelcontextprotocol/server": "2.4.0",
     "@phosphor-icons/react": "^2.1.10",
     "agents": "*",
     "hono": "^4.13.5",

diff --git a/examples/mcp-worker/package.json b/examples/mcp-worker/package.json
@@ -10,8 +10,8 @@
   },
   "dependencies": {
     "@cloudflare/kumo": "^2.6.0",
-    "@modelcontextprotocol/sdk": "1.32.1",
-    "@modelcontextprotocol/server": "2.3.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@modelcontextprotocol/server": "2.4.0",
     "@phosphor-icons/react": "^2.1.10",
     "agents": "*",
     "react": "^19.2.7",

diff --git a/examples/mcp/package.json b/examples/mcp/package.json
@@ -9,7 +9,7 @@
   },
   "dependencies": {
     "@cloudflare/kumo": "^2.6.0",
-    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "@phosphor-icons/react": "^2.1.10",
     "agents": "*",
     "react": "^19.2.7",

diff --git a/examples/next/mcp-client/package.json b/examples/next/mcp-client/package.json
@@ -12,7 +12,7 @@
   },
   "dependencies": {
     "@cloudflare/kumo": "^2.6.0",
-    "@modelcontextprotocol/client": "2.3.1",
+    "@modelcontextprotocol/client": "2.4.0",
     "@phosphor-icons/react": "^2.1.10",
     "agents": "*",
     "react": "^19.2.7",

diff --git a/examples/playground/package.json b/examples/playground/package.json
@@ -12,8 +12,8 @@
     "@cloudflare/ai-chat": "*",
     "@cloudflare/codemode": "*",
     "@cloudflare/kumo": "^2.6.0",
-    "@modelcontextprotocol/sdk": "1.32.1",
-    "@modelcontextprotocol/server": "2.3.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@modelcontextprotocol/server": "2.4.0",
     "@phosphor-icons/react": "^2.1.10",
     "@streamdown/code": "^1.1.1",
     "agents": "*",

diff --git a/examples/webmcp/package.json b/examples/webmcp/package.json
@@ -9,7 +9,7 @@
   },
   "dependencies": {
     "@cloudflare/kumo": "^2.6.0",
-    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "@phosphor-icons/react": "^2.1.10",
     "agents": "*",
     "zod": "^4.6.7"

diff --git a/examples/x402-mcp/package.json b/examples/x402-mcp/package.json
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@cloudflare/kumo": "^2.6.0",
-    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "@phosphor-icons/react": "^2.1.10",
     "@x402/evm": "^2.17.0",
     "agents": "*",

diff --git a/openai-sdk/chess-app/package.json b/openai-sdk/chess-app/package.json
@@ -10,8 +10,8 @@
   },
   "dependencies": {
     "@cloudflare/vite-plugin": "1.62.3",
-    "@modelcontextprotocol/sdk": "1.32.1",
-    "@modelcontextprotocol/server": "2.3.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@modelcontextprotocol/server": "2.4.0",
     "@vitejs/plugin-react": "^6.0.3",
     "agents": "*",
     "chess.js": "^1.4.0",

diff --git a/openai-sdk/pizzaz/package.json b/openai-sdk/pizzaz/package.json
@@ -7,7 +7,7 @@
     "start": "wrangler dev"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "agents": "*",
     "zod": "^4.6.7"
   }

diff --git a/package.json b/package.json
@@ -39,7 +39,7 @@
     "@cloudflare/vite-plugin": "1.62.3",
     "@cloudflare/vitest-pool-workers": "^0.19.1",
     "@cloudflare/workers-types": "^5.20261014.1",
-    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/sdk": "1.32.2",
     "@openai/agents": "^0.12.0",
     "@openai/agents-extensions": "^0.12.0",
     "@phosphor-icons/react": "^2.1.10",

diff --git a/packages/agents/conformance/README.md b/packages/agents/conformance/README.md
@@ -25,8 +25,8 @@ the current protocol lane.
 
 | Command                              | Server protocol/referee selection | Scenarios | Current result                 |
 | ------------------------------------ | --------------------------------- | --------- | ------------------------------ |
-| `test:conformance:client:stateless`  | `2026-07-28`                      | 33        | 30 clean / 3 expected failures |
-| `test:conformance:client:2025-11-25` | `2025-11-25`                      | 19        | 17 clean / 2 expected failures |
+| `test:conformance:client:stateless`  | `2026-07-28`                      | 33        | 31 clean / 2 expected failures |
+| `test:conformance:client:2025-11-25` | `2025-11-25`                      | 19        | 18 clean / 1 expected failure  |
 | `test:conformance:client:2025-06-18` | `2025-06-18`                      | 5         | 5 clean                        |
 | `test:conformance:client:2025-03-26` | `2025-03-26` OAuth/backcompat     | 2         | 2 clean                        |
 

diff --git a/packages/agents/conformance/baseline-client-2025-11-25.yml b/packages/agents/conformance/baseline-client-2025-11-25.yml
@@ -1,13 +1,8 @@
 # SDK v2 client against 2025-11-25 stateful servers.
 client:
-  # SHOULD-level only: the built-in provider uses Dynamic Client Registration
-  # instead of a URL-based Client ID Metadata Document.
-  # Impact if unchanged: servers that require CIMD rather than DCR need a
-  # custom OAuth provider.
-  - auth/basic-cimd
-
   # The default scope step-up budget produces four authorization attempts;
-  # the referee's SHOULD-level limit is three or fewer.
+  # the referee's SHOULD-level limit is three or fewer. Fixed by the
+  # step-up round limit in cloudflare/agents#2663; remove this entry with it.
   # Impact if unchanged: a permanently unsatisfiable insufficient_scope
   # challenge can send the user through one additional OAuth round-trip before
   # the client stops retrying.

diff --git a/packages/agents/conformance/baseline-client-2026-07-28.yml b/packages/agents/conformance/baseline-client-2026-07-28.yml
@@ -1,22 +1,18 @@
 # SDK v2 client against the latest published conformance protocol revision.
 # Every entry is executed by alpha.12; run-suite.mjs rejects unseen entries.
 client:
-  # SHOULD-level only: the built-in provider uses Dynamic Client Registration
-  # instead of a URL-based Client ID Metadata Document.
-  # Impact if unchanged: servers that require CIMD rather than DCR need a
-  # custom OAuth provider.
-  - auth/basic-cimd
-
   # The default scope step-up budget produces four authorization attempts;
-  # the referee's SHOULD-level limit is three or fewer.
+  # the referee's SHOULD-level limit is three or fewer. Fixed by the
+  # step-up round limit in cloudflare/agents#2663; remove this entry with it.
   # Impact if unchanged: a permanently unsatisfiable insufficient_scope
   # challenge can send the user through one additional OAuth round-trip before
   # the client stops retrying.
   - auth/scope-retry-limit
 
-  # Alpha.12 omits resultType after negotiating 2026-07-28. The final draft
-  # requires servers implementing that revision to include it; the
-  # absent-means-complete bridge applies only to earlier revisions. All five
-  # MRTR wire assertions pass before the fixture's invalid final result.
+  # Referee bug (modelcontextprotocol/conformance#475): test_mrtr_no_result_type
+  # omits resultType after negotiating 2026-07-28. The released spec
+  # (basic/index, ResultType) requires 2026-07-28 servers to include it and
+  # limits absent-means-complete to earlier-revision servers, so the SDK v2
+  # client rejects the result. All five MRTR wire checks pass first.
   # Impact if unchanged: none for conforming 2026-07-28 servers.
   - sep-2322-client-request-state
diff --git a/packages/agents/conformance/baseline-server-handler-legacy-compat.yml b/packages/agents/conformance/baseline-server-handler-legacy-compat.yml
@@ -1,4 +1,6 @@
-# SDK v2 handler's explicit Legacy compatibility path.
+# SDK v2 handler's explicit Legacy compatibility path (deprecated).
+# These need a server-to-client channel or a durable event stream, which a
+# stateless request does not have; they are kept rather than fixed.
 # All 33 scenarios execute; this is not the alpha harness's smaller `active`
 # subset. Complete sessionful compatibility is tested in the legacy lanes.
 server:

diff --git a/...s/conformance/baseline-server-handler.yml → ...rmance/baseline-server-handler-legacy.yml b/...s/conformance/baseline-server-handler.yml → ...rmance/baseline-server-handler-legacy.yml
@@ -1,4 +1,6 @@
 # createLegacyMcpHandler + WorkerTransport at 2025-11-25.
+# Deprecated surface: these stay baselined rather than fixed. createMcpHandler
+# passes all three at 2026-07-28 (server-handler lane).
 server:
   # SDK v1's Zod conversion emits draft-07 and strips JSON Schema 2020-12
   # $defs/additionalProperties fields.

diff --git a/packages/agents/conformance/baseline-server-mcp-agent.yml b/packages/agents/conformance/baseline-server-mcp-agent.yml
@@ -1,4 +1,6 @@
 # Retained SDK v1 McpAgent endpoint at 2025-11-25.
+# Deprecated surface: these stay baselined rather than fixed. createMcpHandler
+# passes all three at 2026-07-28 (server-handler lane).
 server:
   # SDK v1's Zod conversion emits draft-07 and strips JSON Schema 2020-12
   # $defs/additionalProperties fields.

diff --git a/packages/agents/conformance/run.sh b/packages/agents/conformance/run.sh
@@ -116,7 +116,7 @@ case "$MODE" in
     ;;
   server-handler-legacy)
     run_server "$WORKER_ORIGIN/mcp-handler-legacy" 2025-11-25 \
-      conformance/baseline-server-handler.yml "$@"
+      conformance/baseline-server-handler-legacy.yml "$@"
     ;;
   server-mcp-agent)
     run_server "$WORKER_ORIGIN/mcp-agent" 2025-11-25 \

diff --git a/packages/agents/conformance/vendor/README.md b/packages/agents/conformance/vendor/README.md
@@ -4,17 +4,19 @@
 v2 conformance fixture:
 
 - repository: `https://github.com/modelcontextprotocol/typescript-sdk`
-- package tag: `@modelcontextprotocol/server@2.3.1`
-- commit: `fcef852f6cdafea07f36cf6fae69b37c8adf85be`
+- package tag: `@modelcontextprotocol/server@2.4.0`
+- commit: `951fe5603a7ec0b2dcb6a0b95d92cd86f93ad9e5`
 - source: `test/conformance/src/everythingServer.ts`
-- source SHA-256: `2442aebdd2f97995ff60c80ee8688603323b7c33cb9ac07ba87f47771ac5d119`
+- source SHA-256: `1ec5c8e22fc4a9daf37d6b34ee692c6ec4d097f314fcde4d7f26d241fdbbc408`
 
 The local fixture keeps the upstream registrations while removing the
 Node/Express entrypoint, Node transports, session registry, and Node event
 store. It exports one factory for the Agents workerd conformance worker and uses
 Web Crypto for request-state integrity. The scope-challenge registrations are
 kept, but the upstream entrypoint's middleware that stamps `AuthInfo` from fixed
-bearer tokens is not, so those checks always pass here.
+bearer tokens is not, so those checks always pass here. The SEP-2640 skills
+catalog (`conformanceSkills.attach`, added in 2.4.0) is also left out: skills
+are an extension, and the core lanes never select extension scenarios.
 
 When updating the SDK pin, fetch the source at the recorded commit, verify its
 SHA-256, inspect a no-index diff against this file, and port only registration

diff --git a/packages/agents/conformance/worker.ts b/packages/agents/conformance/worker.ts
@@ -1,6 +1,8 @@
 import {
   Agent,
+  type AgentMcpOAuthProvider,
   type AgentNamespace,
+  DurableObjectOAuthClientProvider,
   getAgentByName,
   routeAgentRequest
 } from "../src/index.ts";
@@ -47,6 +49,10 @@ type Env = {
 
 const SERVER_NAME = "conformance";
 
+// Fixed client_id the referee's auth/basic-cimd scenario expects.
+const CIMD_CLIENT_METADATA_URL =
+  "https://conformance-test.local/client-metadata.json";
+
 type RunRequest = { scenario: string; serverUrl: string; context?: string };
 
 type RunResult =
@@ -59,6 +65,19 @@ export class ConformanceHost extends Agent<Env> {
   private _scenario: string | undefined;
   private _mrtrIsolationCallMade = false;
 
+  // Offer a Client ID Metadata Document URL. Authorization servers that
+  // advertise CIMD support receive it as the client_id; the rest still use
+  // dynamic client registration. The referee accepts this fixed URL without
+  // fetching it.
+  createMcpOAuthProvider(callbackUrl: string): AgentMcpOAuthProvider {
+    return new DurableObjectOAuthClientProvider(
+      this.ctx.storage,
+      this.name,
+      callbackUrl,
+      { clientMetadataUrl: CIMD_CLIENT_METADATA_URL }
+    );
+  }
+
   onStart() {
     // Accept elicitation requests. Form-mode defaults are applied by the SDK
     // client because the connection advertises `form.applyDefaults` (SEP-1034).