agents 0.19.0 → 0.20.0

package/docs/mcp-servers.md

@@ -4,23 +4,27 @@ This guide covers the different ways to create MCP servers with the Agents SDK a
 
 ## Choosing an Approach
 
-| Approach                                       | Stateful? | Requires Durable Objects? | Best for                                       |
-| ---------------------------------------------- | --------- | ------------------------- | ---------------------------------------------- |
-| `createMcpHandler()`                           | No        | No                        | Stateless tools, simplest setup                |
-| `McpAgent`                                     | Yes       | Yes                       | Stateful tools, per-session state, elicitation |
-| Raw `WebStandardStreamableHTTPServerTransport` | No        | No                        | Full control, no SDK dependency                |
+| Approach                                       | Stateful? | Requires Durable Objects? | Best for                                          |
+| ---------------------------------------------- | --------- | ------------------------- | ------------------------------------------------- |
+| `createMcpHandler()`                           | No        | No                        | New servers and the draft MCP protocol            |
+| `McpAgent` (deprecated legacy path)            | Yes       | Yes                       | Existing stateful SDK v1 deployments              |
+| Raw `WebStandardStreamableHTTPServerTransport` | No        | No                        | Low-level control without the Agents HTTP wrapper |
 
-- **`createMcpHandler()`** is the fastest way to get a stateless MCP server running. Use it when your tools do not need per-session state.
-- **`McpAgent`** gives you a Durable Object per session with built-in state management, elicitation support, and both SSE and Streamable HTTP transports.
-- **Raw transport** gives you full control if you want to use the `@modelcontextprotocol/sdk` directly without the Agents SDK helpers.
+- **`createMcpHandler()`** is the current server-development path. It serves draft MCP `2026-07-28` and supports stateless published 2025 clients by default.
+- **`McpAgent`** is a retained, feature-frozen SDK v1 path for existing stateful deployments. New servers should use `createMcpHandler()`.
+- **Raw transport** gives you low-level control if the standard handler lifecycle is not suitable.
 
 ## Stateless MCP Server with `createMcpHandler()`
 
-The simplest way to create an MCP server. No Durable Objects or bindings required:
+The simplest way to create an MCP server. Install the exact SDK v2 server peer, then use the isolated server entry point so legacy Agents transports and MCP clients stay out of your Worker bundle:
+
+```sh
+pnpm add agents @modelcontextprotocol/server@2.0.0-beta.5 zod
+```
 
 ```typescript
-import { createMcpHandler } from "agents/mcp";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
+import { createMcpHandler } from "agents/mcp/server";
 import { z } from "zod";
 
 function createServer() {
@@ -44,45 +48,77 @@ function createServer() {
 }
 
 export default {
-  fetch: async (request: Request, env: Env, ctx: ExecutionContext) => {
-    const server = createServer();
-    return createMcpHandler(server)(request, env, ctx);
+  fetch(request, env, ctx) {
+    return createMcpHandler(createServer)(request, env, ctx);
   }
-};
+} satisfies ExportedHandler;
 ```
 
-> **Important:** Create a new `McpServer` instance per request. The MCP SDK does not allow connecting an already-connected server to a new transport.
+`createMcpHandler` requires a factory so concurrent Worker requests receive isolated server instances. A function input is always treated as an SDK v2 factory.
 
-### `createMcpHandler` Options
+### `createMcpHandler` options
 
 ```typescript
-createMcpHandler(server, {
-  route: "/mcp",              // path to handle (default: "/mcp")
-  enableJsonResponse: true,   // use JSON responses instead of SSE streaming
-  sessionIdGenerator: () => crypto.randomUUID(),
-  corsOptions: { ... },       // CORS configuration
-  authContext: { props: {} },  // manually set auth context
-  transport: workerTransport   // provide your own WorkerTransport instance
+createMcpHandler(() => createServer(), {
+  route: "/mcp", // exact path to handle (default: "/mcp")
+  corsOptions: {
+    origin: "https://app.example.com"
+  },
+  allowedHostnames: ["mcp.example.com"], // custom-domain Host policy
+  allowedOriginHostnames: ["app.example.com"], // browser Origin policy
+  authContext: { props: {} }, // optional application props override
+  legacy: "stateless", // upstream default; use "reject" for Stateless-only
+  responseMode: "auto" // upstream SDK response shaping
 });
 ```
 
+All upstream SDK v2 handler options pass through. Use `createLegacyMcpHandler` for WorkerTransport, storage, session, and event-store options.
+
+The handler validates every present `Origin` header before serving the request. It rejects malformed, opaque, and non-HTTP origins. Requests without `Origin` remain valid for non-browser MCP clients.
+
+Its default allowlist includes localhost-class origins and the endpoint's `workers.dev` hostname. A concrete `corsOptions.origin` adds that hostname automatically. The handler also applies matching Host checks to localhost and `workers.dev` endpoints. For a custom domain with wildcard CORS, configure `allowedHostnames` and `allowedOriginHostnames` explicitly. Values are hostnames without a scheme or port, and matching ignores the Origin's scheme and port.
+
+Pass `allowedOriginHostnames: "*"` only when equivalent Origin validation runs in trusted middleware before the handler. This explicitly disables the handler's Origin check, including malformed and opaque Origin rejection. MCP HTTP servers are required to validate browser Origins, so do not use this as an unauthenticated public-server shortcut.
+
+### 2025 compatibility and elicitation
+
+The default `legacy: "stateless"` lane supports ordinary 2025 tools, resources, and prompts. It has no session return path for push-style server-to-client requests; attempts to sample, elicit, or list roots fail immediately with guidance to use a sessionful transport.
+
+Applications that must serve both generations can route before `createMcpHandler`: send Stateless requests to a strict handler and Legacy requests to an existing session-addressed Agent or transport. See [`examples/mcp-elicitation-mrtr`](../../examples/mcp-elicitation-mrtr/) for Stateless Elicitation and [`examples/mcp-elicitation`](../../examples/mcp-elicitation/) for Legacy Elicitation.
+
+For an explicit Legacy handler, use the retained Legacy API:
+
+```typescript
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createLegacyMcpHandler } from "agents/mcp";
+
+const server = new McpServer({ name: "legacy", version: "1.0.0" });
+export default createLegacyMcpHandler(server);
+```
+
+Passing an SDK v1 server directly to `createMcpHandler` still forwards to this API for compatibility, but that overload is deprecated, emits a migration warning, and is removed in the next major release. `createLegacyMcpHandler` and `WorkerTransport` themselves are not deprecated.
+
 ### Accessing Authenticated User Context
 
-When your MCP server is wrapped with `OAuthProvider` from `@cloudflare/workers-oauth-provider`, authenticated user information is available inside tools via `getMcpAuthContext()`:
+When your MCP server is wrapped with `OAuthProvider` from `@cloudflare/workers-oauth-provider`, provider-issued tokens are available through standard SDK v2 `AuthInfo`. The existing `getMcpAuthContext()` application-props helper remains supported:
 
 ```typescript
-import { createMcpHandler, getMcpAuthContext } from "agents/mcp";
+import { createMcpHandler, getMcpAuthContext } from "agents/mcp/server";
 
 server.registerTool(
   "whoami",
   { description: "Returns the authenticated user" },
-  async () => {
+  async (context) => {
     const auth = getMcpAuthContext();
     return {
       content: [
         {
           type: "text",
-          text: auth ? JSON.stringify(auth.props) : "Not authenticated"
+          text: JSON.stringify({
+            clientId: context.http?.authInfo?.clientId,
+            scopes: context.http?.authInfo?.scopes,
+            props: auth?.props
+          })
         }
       ]
     };
@@ -90,11 +126,11 @@ server.registerTool(
 );
 ```
 
-The `OAuthProvider` sets `ctx.props` on the execution context, which `createMcpHandler` automatically picks up and makes available via `getMcpAuthContext()`.
+Do not log or return `context.http.authInfo.token`. External-token resolvers continue providing `getMcpAuthContext().props` but do not synthesize incomplete standard metadata.
 
-## Stateful MCP Server with `McpAgent`
+## Stateful MCP Server with `McpAgent` (legacy)
 
-`McpAgent` gives each client session its own Durable Object with persistent state. Use this when your tools need to track per-session data.
+`McpAgent` gives each client session its own Durable Object with persistent state. It remains available for existing SDK v1 deployments but is deprecated and feature-frozen; new servers should use the stateless handler or explicitly compose a separate legacy route where a session is required.
 
 ### Writing TinyMCP
 
@@ -428,76 +464,77 @@ The `jurisdiction` option accepts any value supported by [Cloudflare's Durable O
 
 ## Elicitation (Human-in-the-Loop)
 
-MCP servers can request additional input from the user during a tool call using elicitation. This is useful for confirmation dialogs, requesting amounts, or any interactive tool flow.
+MCP servers can request additional input during a tool call. The implementation differs by protocol generation.
+
+### Stateless Elicitation
 
-Elicitation is supported via `McpAgent` (which manages the request/response lifecycle through Durable Object storage) or via `WorkerTransport` (for stateful non-McpAgent setups).
+For Stateless Elicitation, return `inputRequired(...)`. The client gathers the input and retries the request with SDK-managed `requestState` and `inputResponses`; the Worker does not suspend while a person responds.
 
 ```typescript
-import { McpAgent } from "agents/mcp";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import {
+  McpServer,
+  acceptedContent,
+  inputRequired
+} from "@modelcontextprotocol/server";
+import { createMcpHandler } from "agents/mcp/server";
 import { z } from "zod";
 
-export class MyMCP extends McpAgent<Env, { counter: number }> {
-  server = new McpServer({ name: "Elicitation Demo", version: "1.0.0" });
-
-  initialState = { counter: 0 };
-
-  async init() {
-    this.server.registerTool(
-      "increase-counter",
-      {
-        description: "Increase the counter",
-        inputSchema: {
-          confirm: z.boolean().describe("Do you want to increase the counter?")
-        }
-      },
-      async ({ confirm }, extra) => {
-        if (!confirm) {
-          return { content: [{ type: "text", text: "Cancelled." }] };
-        }
-
-        const result = await this.server.server.elicitInput(
-          {
-            message: "By how much?",
-            requestedSchema: {
-              type: "object",
-              properties: {
-                amount: { type: "number", title: "Amount" }
-              },
-              required: ["amount"]
-            }
-          },
-          { relatedRequestId: extra.requestId }
-        );
-
-        if (result.action !== "accept" || !result.content?.amount) {
-          return { content: [{ type: "text", text: "Cancelled." }] };
-        }
-
-        const amount = Number(result.content.amount);
-        this.setState({ counter: this.state.counter + amount });
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Counter increased by ${amount}, now ${this.state.counter}`
-            }
-          ]
-        };
+function createServer() {
+  const server = new McpServer({
+    name: "Stateless Elicitation Demo",
+    version: "1.0.0"
+  });
+  server.registerTool(
+    "ask-name",
+    { inputSchema: z.object({}) },
+    async (_args, context) => {
+      const answer = acceptedContent(
+        context.mcpReq.inputResponses,
+        "name",
+        z.object({ name: z.string() })
+      );
+      if (!answer) {
+        return inputRequired({
+          inputRequests: {
+            name: inputRequired.elicit({
+              message: "What is your name?",
+              requestedSchema: {
+                type: "object",
+                properties: { name: { type: "string" } },
+                required: ["name"]
+              }
+            })
+          }
+        });
       }
-    );
-  }
+      return { content: [{ type: "text", text: `Hello ${answer.name}` }] };
+    }
+  );
+  return server;
 }
 
-export default MyMCP.serve("/mcp");
+export default {
+  fetch(request, env, ctx) {
+    return createMcpHandler(createServer, { legacy: "reject" })(
+      request,
+      env,
+      ctx
+    );
+  }
+} satisfies ExportedHandler;
 ```
 
-See the [`examples/mcp-elicitation`](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation) example for a full working demo.
+See [`examples/mcp-elicitation-mrtr`](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr) for a two-round Stateless Elicitation example.
+
+### Legacy Elicitation
+
+Existing Legacy deployments send pushed `elicitation/create` requests over a session-addressed response stream. Use `McpAgent` or `createLegacyMcpHandler` with `WorkerTransport` when that behavior must be retained.
+
+See [`examples/mcp-elicitation`](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation) for form- and URL-mode Legacy Elicitation with Durable Object state and SSE replay.
 
 ## WorkerTransport
 
-`WorkerTransport` is a server-side transport for running MCP servers in stateless Workers while optionally persisting session state. It is used internally by `createMcpHandler()` but can also be used directly for advanced scenarios like stateful sessions without `McpAgent`.
+`WorkerTransport` is the retained Agents transport for stateful Legacy deployments. Use it with `createLegacyMcpHandler` for persistent sessions, storage, event replay, and other explicit legacy configurations. The Stateless handler's Legacy compatibility lane uses the SDK v2 web-standard transport instead and does not import `WorkerTransport`.
 
 ```typescript
 import { WorkerTransport, type TransportState } from "agents/mcp";

package/docs/securing-mcp-servers.md

@@ -6,14 +6,15 @@ Cloudflare's `workers-oauth-provider` lets you secure your MCP Server (or any ap
 
 ```typescript
 import { OAuthProvider, OAuthError } from "@cloudflare/workers-oauth-provider";
-import { createMcpHandler } from "agents/mcp";
+import { McpServer } from "@modelcontextprotocol/server";
+import { createMcpHandler } from "agents/mcp/server";
 
 // A Worker that exposes an MCP server
-const apiHandler = {
-  async fetch(request: Request, env: unknown, ctx: ExecutionContext) {
-    return createMcpHandler(server)(request, env, ctx);
-  }
-};
+function createServer() {
+  return new McpServer({ name: "authenticated-server", version: "1.0.0" });
+}
+
+const apiHandler = createMcpHandler(createServer);
 
 // Wrap with OAuth protection
 export default new OAuthProvider({
@@ -28,6 +29,8 @@ export default new OAuthProvider({
 });
 ```
 
+For provider-issued tokens, SDK v2 tool callbacks receive standard metadata at `context.http.authInfo`, while `getMcpAuthContext().props` retains the existing application-props shape. Treat `authInfo.token` and `authInfo.extra.props` as sensitive and do not log or return them.
+
 However, most MCP servers aren't just servers, they can actually be OAuth clients too. Your MCP server might sit between Claude Desktop and a third-party API like GitHub or Google. To Claude, you're a server. To GitHub, you're a client. This allows your users to authenticate and use their GitHub credentials to access your MCP server. We call this a proxy server.
 
 There are a few security footguns to securely building a proxy server. The rest of this document aims to outline best practises to securing an MCP server.

package/package.json

@@ -9,7 +9,7 @@
     "durable objects"
   ],
   "type": "module",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "license": "MIT",
   "repository": {
     "directory": "packages/agents",
@@ -26,8 +26,6 @@
   "dependencies": {
     "@babel/plugin-proposal-decorators": "^8.0.2",
     "@cfworker/json-schema": "^4.1.1",
-    "@cloudflare/codemode": "^0.5.0",
-    "@modelcontextprotocol/sdk": "1.29.0",
     "@rolldown/plugin-babel": "^0.2.3",
     "cron-schedule": "^6.0.0",
     "esbuild": "^0.28.1",
@@ -40,7 +38,11 @@
   },
   "devDependencies": {
     "@ai-sdk/react": "^4.0.0",
-    "@modelcontextprotocol/conformance": "0.1.16",
+    "@cloudflare/codemode": "^0.5.1",
+    "@modelcontextprotocol/client": "2.0.0-beta.5",
+    "@modelcontextprotocol/conformance-v2": "npm:@modelcontextprotocol/conformance@0.2.0-alpha.10",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@modelcontextprotocol/server": "2.0.0-beta.5",
     "@tanstack/ai": "0.38.0",
     "@types/react": "^19.2.17",
     "@types/yargs": "^17.0.35",
@@ -57,6 +59,10 @@
   },
   "peerDependencies": {
     "@ai-sdk/react": "^3.0.0 || ^4.0.0",
+    "@cloudflare/codemode": ">=0.5.0",
+    "@modelcontextprotocol/client": "2.0.0-beta.5",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@modelcontextprotocol/server": "2.0.0-beta.5",
     "@tanstack/ai": ">=0.10.2 <1.0.0",
     "@x402/core": "^2.0.0",
     "@x402/evm": "^2.0.0",
@@ -71,6 +77,9 @@
     "@ai-sdk/react": {
       "optional": true
     },
+    "@cloudflare/codemode": {
+      "optional": true
+    },
     "@tanstack/ai": {
       "optional": true
     },
@@ -130,6 +139,11 @@
       "import": "./dist/mcp/client.js",
       "require": "./dist/mcp/client.js"
     },
+    "./mcp/server": {
+      "types": "./dist/mcp/server.d.ts",
+      "import": "./dist/mcp/server.js",
+      "require": "./dist/mcp/server.js"
+    },
     "./mcp/do-oauth-client-provider": {
       "types": "./dist/mcp/do-oauth-client-provider.d.ts",
       "import": "./dist/mcp/do-oauth-client-provider.js",
@@ -293,9 +307,16 @@
     "test:webmcp": "vitest --project webmcp",
     "test:x402": "vitest --project x402",
     "test:e2e": "vitest --run -c src/e2e-tests/vitest.config.ts",
-    "test:conformance": "pnpm run test:conformance:client && pnpm run test:conformance:server:mcp-agent && pnpm run test:conformance:server:handler",
-    "test:conformance:client": "bash conformance/run.sh client --suite all",
+    "test:conformance": "pnpm run test:conformance:client && pnpm run test:conformance:server",
+    "test:conformance:client": "pnpm run test:conformance:client:stateless && pnpm run test:conformance:client:2025-11-25 && pnpm run test:conformance:client:2025-06-18 && pnpm run test:conformance:client:2025-03-26",
+    "test:conformance:client:stateless": "bash conformance/run.sh client-stateless",
+    "test:conformance:client:2025-11-25": "bash conformance/run.sh client-2025-11-25",
+    "test:conformance:client:2025-06-18": "bash conformance/run.sh client-2025-06-18",
+    "test:conformance:client:2025-03-26": "bash conformance/run.sh client-2025-03-26",
+    "test:conformance:server": "pnpm run test:conformance:server:handler && pnpm run test:conformance:server:handler:legacy-compat && pnpm run test:conformance:server:handler:legacy && pnpm run test:conformance:server:mcp-agent",
     "test:conformance:server:mcp-agent": "bash conformance/run.sh server-mcp-agent",
-    "test:conformance:server:handler": "bash conformance/run.sh server-handler"
+    "test:conformance:server:handler": "bash conformance/run.sh server-handler",
+    "test:conformance:server:handler:legacy-compat": "bash conformance/run.sh server-handler-legacy-compat",
+    "test:conformance:server:handler:legacy": "bash conformance/run.sh server-handler-legacy"
   }
 }