agents 0.29.0 → 0.30.1

package/docs/mcp-transports.md

@@ -1,314 +1,55 @@
 # MCP Transports
 
-This guide explains the different transport options for connecting to MCP servers with the Agents SDK.
+This page covers the transport your MCP server uses and the transports an Agent can use to connect to other MCP servers.
 
-For a primer on MCP servers, see [Creating MCP Servers](./mcp-servers.md).
+## Server: Streamable HTTP
 
-## Streamable HTTP Transport (Recommended)
-
-The Agents SDK has two server paths:
-
-- Current SDK v2 servers use `createMcpHandler`, a per-request stateless Worker handler with no Durable Object or WebSocket bridge.
-- Retained SDK v1 servers use the deprecated, feature-frozen `McpAgent`, which provides sessionful transports through a Durable Object and internal WebSocket bridge.
-
-The current stateless handler also accepts stateless 2025-era Streamable HTTP requests by default. It does not expose standalone legacy SSE.
-
-### Legacy `McpAgent` architecture
-
-When a client connects to your MCP server:
-
-1. The client makes an HTTP request to your Worker with a JSON-RPC message in the body
-2. Your Worker upgrades the connection to a WebSocket
-3. The WebSocket connects to your `McpAgent` Durable Object which manages connection state
-4. JSON-RPC messages flow bidirectionally over the WebSocket
-5. Your Worker streams responses back to the client using Server-Sent Events (SSE)
-
-This is all handled automatically by the `McpAgent.serve()` method:
+[`createMcpHandler`](./mcp-servers.md) serves Streamable HTTP. Each request is handled on its own, with a fresh `McpServer` from your factory, so there are no sessions, Durable Objects, or WebSockets behind the endpoint.
 
 ```typescript
-import { McpAgent } from "agents/mcp";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-
-export class MyMCP extends McpAgent {
-  server = new McpServer({ name: "Demo", version: "1.0.0" });
-
-  async init() {
-    // Define your tools, resources, prompts
-  }
-}
-
-// Serve with Streamable HTTP transport
-export default MyMCP.serve("/mcp");
-```
+import { createMcpHandler } from "agents/mcp/server";
 
-The `serve()` method returns a Worker with a `fetch` handler that:
-
-- Handles CORS preflight requests
-- Manages WebSocket upgrades
-- Routes messages to your Durable Object
-
-### Connection from clients
-
-The Agents MCP client uses `"auto"` by default. It tries Streamable HTTP first and falls back to legacy SSE only when the endpoint reports that Streamable HTTP is unsupported:
-
-```typescript
-await agent.addMcpServer("my-server", "https://your-worker.workers.dev/mcp");
+const handler = createMcpHandler(createServer, { route: "/mcp" });
 ```
 
-## Legacy `McpAgent` Server Auto Transport
-
-The **auto** transport serves both Streamable HTTP and legacy SSE on the same endpoint. Capable clients use Streamable HTTP automatically, while older SSE-only clients continue to work.
+The same endpoint serves:
 
-```typescript
-export default MyMCP.serve("/mcp", { transport: "auto" });
-```
-
-The handler distinguishes between the two protocols based on the request shape — no configuration or content negotiation is required from clients. This is useful when migrating from SSE to Streamable HTTP without breaking existing clients.
+- Stateless clients on draft MCP `2026-07-28`
+- 2025-era Streamable HTTP clients, for tools, resources, and prompts (the default `legacy: "stateless"` lane)
 
-## Legacy `McpAgent` SSE Transport (Deprecated)
+It does not serve the standalone SSE transport. Set `legacy: "reject"` to accept only Stateless clients. See [2025-era clients](./mcp-servers.md#2025-era-clients) for what that lane does not support.
 
-We also support the legacy **SSE (Server-Sent Events)** transport, but it is deprecated in favor of Streamable HTTP.
+## Client: connecting to MCP servers
 
-If you need SSE transport for compatibility:
+An Agent connects to remote MCP servers with `addMcpServer()`. The `transport.type` option picks the transport:
 
 ```typescript
-// Server
-export default MyMCP.serveSSE("/sse");
-
-// Client
-await agent.addMcpServer("my-server", url);
-```
-
-## RPC Transport (Experimental)
-
-The **RPC transport** is a custom transport designed for internal applications where your MCP server and agent are both running on Cloudflare. They can even run in the same Worker! It sends JSON-RPC messages directly over Cloudflare's RPC bindings without going over the public internet.
-
-### Why use RPC transport?
-
-- **Faster**: No network overhead - direct function calls
-- **Simpler**: No HTTP endpoints, no connection management
-- **Internal only**: Perfect for agents calling MCP servers within the same Worker
-
-**Note**: RPC transport does not support authentication. Use HTTP/SSE for external connections that require OAuth.
-
-### Connecting an Agent to an McpAgent via RPC
-
-The RPC transport uses Durable Object bindings to connect your `Agent` (MCP client) directly to your `McpAgent` (MCP server).
-
-#### Step 1: Define your MCP server
-
-Create your `McpAgent` with the tools you want to expose:
-
-```typescript
-import { McpAgent } from "agents/mcp";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-
-type State = { counter: number };
-
-export class MyMCP extends McpAgent<Env, State> {
-  server = new McpServer({ name: "MyMCP", version: "1.0.0" });
-  initialState: State = { counter: 0 };
-
-  async init() {
-    this.server.tool(
-      "add",
-      "Add to the counter",
-      { amount: z.number() },
-      async ({ amount }) => {
-        this.setState({ counter: this.state.counter + amount });
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Added ${amount}, total is now ${this.state.counter}`
-            }
-          ]
-        };
-      }
-    );
-  }
-}
-```
-
-#### Step 2: Connect your Agent to the MCP server
-
-In your `Agent`, call `addMcpServer()` with the Durable Object binding in `onStart()`:
-
-```typescript
-import { AIChatAgent } from "agents/ai-chat-agent";
-
-export class Chat extends AIChatAgent<Env> {
-  async onStart(): Promise<void> {
-    // Pass the DO namespace binding directly
-    await this.addMcpServer("my-mcp", this.env.MyMCP);
-  }
-
-  async onChatMessage(onFinish) {
-    const allTools = this.mcp.getAITools();
-
-    const result = streamText({
-      model,
-      tools: allTools
-      // ...
-    });
+// Default: try Streamable HTTP, fall back to SSE
+await this.addMcpServer("my-server", "https://example.com/mcp");
 
-    return createUIMessageStreamResponse({ stream: result });
-  }
-}
-```
-
-RPC connections are automatically restored after Durable Object hibernation, just like HTTP connections. The binding name and props are persisted to storage so the connection can be re-established without any extra code.
-
-**Deduplication:** For RPC transport, if `addMcpServer` is called with a name that already has an active connection, the existing connection is returned instead of creating a duplicate. For HTTP transport, deduplication matches on both server name and URL (see [MCP Client API](./mcp-client.md) for details). This makes it safe to call `addMcpServer` in `onStart()` without worrying about creating multiple connections on restart.
-
-#### Step 3: Configure Durable Object bindings
-
-In your `wrangler.jsonc`, define bindings for both Durable Objects:
-
-```jsonc
-{
-  "durable_objects": {
-    "bindings": [
-      { "name": "Chat", "class_name": "Chat" },
-      { "name": "MyMCP", "class_name": "MyMCP" }
-    ]
-  },
-  "migrations": [
-    {
-      "new_sqlite_classes": ["MyMCP", "Chat"],
-      "tag": "v1"
-    }
-  ]
-}
-```
-
-#### Step 4: Set up your Worker fetch handler
-
-Route requests to your Chat agent:
-
-```typescript
-import { routeAgentRequest } from "agents";
-
-export default {
-  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
-    const url = new URL(request.url);
-
-    // Optionally expose the MCP server via HTTP as well
-    if (url.pathname.startsWith("/mcp")) {
-      return MyMCP.serve("/mcp").fetch(request, env, ctx);
-    }
-
-    const response = await routeAgentRequest(request, env);
-    if (response) return response;
-
-    return new Response("Not found", { status: 404 });
-  }
-};
-```
-
-### Passing props from client to server
-
-Since RPC transport does not have an OAuth flow, you can pass user context (like userId, role, etc.) directly as props:
-
-```typescript
-await this.addMcpServer("my-mcp", this.env.MyMCP, {
-  props: { userId: "user-123", role: "admin" }
+// Force a transport
+await this.addMcpServer("my-server", "https://example.com/mcp", {
+  transport: { type: "streamable-http" }
 });
-```
 
-Your `McpAgent` can then access these props:
-
-```typescript
-export class MyMCP extends McpAgent<
-  Env,
-  State,
-  { userId?: string; role?: string }
-> {
-  async init() {
-    this.server.tool("whoami", "Get current user info", {}, async () => {
-      const userId = this.props?.userId || "anonymous";
-      const role = this.props?.role || "guest";
-
-      return {
-        content: [{ type: "text", text: `User ID: ${userId}, Role: ${role}` }]
-      };
-    });
+// Send extra headers, for example an API key
+await this.addMcpServer("my-server", "https://example.com/mcp", {
+  transport: {
+    type: "streamable-http",
+    headers: { Authorization: `Bearer ${this.env.API_KEY}` }
   }
-}
-```
-
-The props are:
-
-- **Type-safe**: TypeScript extracts the Props type from your McpAgent generic
-- **Persistent**: Stored in Durable Object storage via `updateProps()`
-- **Available immediately**: Set before any tool calls are made
-
-This is useful for:
-
-- User authentication context
-- Tenant/organization IDs
-- Feature flags or permissions
-- Any per-connection configuration
-
-### How RPC transport works under the hood
-
-When you call `addMcpServer()` with a Durable Object binding, the SDK:
-
-1. Creates an `RPCClientTransport` that wraps the DO stub
-2. Calls `handleMcpMessage()` on the `McpAgent` for each JSON-RPC message
-3. The `McpAgent` routes messages through its `RPCServerTransport` to the MCP server
-4. Responses flow back synchronously through the RPC call
-
-This happens entirely within your Worker's execution context using Cloudflare's RPC mechanism - no HTTP, no WebSockets, no public internet.
-
-The RPC transport fully supports:
-
-- JSON-RPC 2.0 validation (via the MCP SDK's schema)
-- Batch requests
-- Notifications (messages without `id` field)
-- Automatic reconnection after Durable Object hibernation (when called from `onStart()`)
-
-### Configuring RPC Transport Server Timeout
-
-The RPC transport has a configurable timeout for waiting for tool responses. By default, the server will wait **60 seconds** for a tool handler to respond. You can customize this by overriding `getRpcTransportOptions()` in your `McpAgent`:
-
-```typescript
-export class MyMCP extends McpAgent<Env, State> {
-  server = new McpServer({ name: "MyMCP", version: "1.0.0" });
-
-  protected getRpcTransportOptions() {
-    return { timeout: 120000 }; // 2 minutes
-  }
-
-  async init() {
-    this.server.tool(
-      "long-running-task",
-      "A tool that takes a while",
-      { input: z.string() },
-      async ({ input }) => {
-        await longRunningOperation(input);
-        return {
-          content: [{ type: "text", text: "Task completed" }]
-        };
-      }
-    );
-  }
-}
+});
 ```
 
-## Choosing a transport
+| `transport.type`    | Use when                                          |
+| ------------------- | ------------------------------------------------- |
+| `"auto"` (default)  | You do not know which transport the server speaks |
+| `"streamable-http"` | The server supports Streamable HTTP               |
+| `"sse"`             | The server only supports the older SSE transport  |
 
-| Transport                         | Use when                                            | Pros                                       | Cons                                   |
-| --------------------------------- | --------------------------------------------------- | ------------------------------------------ | -------------------------------------- |
-| **Streamable HTTP**               | New servers and external MCP connections            | Current standard transport; supports OAuth | Slight network overhead                |
-| **Client `auto`**                 | The remote server's HTTP transport is not known     | Tries Streamable HTTP, then legacy SSE     | May make a fallback connection attempt |
-| **Legacy `McpAgent` server auto** | An existing server must accept both HTTP transports | Serves both protocols on one endpoint      | Uses the deprecated server path        |
-| **RPC**                           | Internal agents                                     | Fastest, simplest setup                    | No auth, Service Bindings only         |
-| **SSE**                           | Legacy compatibility                                | Backwards compatible                       | Deprecated, use Streamable HTTP        |
+`"auto"` tries Streamable HTTP first and falls back to SSE only when the server reports that Streamable HTTP is unsupported. The client negotiates the protocol version on every connection, so it works with both Stateless and 2025-era servers. See [Connecting to MCP Servers](./mcp-client.md) for OAuth, retries, and the rest of the client API.
 
 ## Examples
 
-- **Streamable HTTP**: See [`examples/mcp`](https://github.com/cloudflare/agents/tree/main/examples/mcp)
-- **RPC Transport**: See [`examples/mcp-rpc-transport`](https://github.com/cloudflare/agents/tree/main/examples/mcp-rpc-transport)
-- **MCP Client**: See [`examples/mcp-client`](https://github.com/cloudflare/agents/tree/main/examples/mcp-client)
+- [`examples/mcp-worker`](https://github.com/cloudflare/agents/tree/main/examples/mcp-worker): a server built with `createMcpHandler`
+- [`examples/mcp-client`](https://github.com/cloudflare/agents/tree/main/examples/mcp-client): an Agent that connects to MCP servers

package/docs/models-pi-ai.md

@@ -166,6 +166,10 @@ A session stores its model as `{ provider, modelId }`, not as a model object, so
 `@cf/…` and `<provider>/<id>` forms there. Options given to `ai(model, options)` do not reach a
 session; set them on `createAI` instead.
 
+A model stream that is cut off, or that sends nothing for `streamIdleTimeoutMs`, ends in an error
+pi-ai's `isRetryableAssistantError()` treats as transient, so the harness retries the turn under
+its retry settings rather than failing it.
+
 `ai.streamFn` is `streamSimple`, bound, for frameworks that take a stream function, such as
 pi-agent-core's `Agent({ streamFn })`.
 
@@ -366,7 +370,7 @@ Every other model in the catalog takes the full set.
 
 ## Beta
 
-This subpath needs `@earendil-works/pi-ai@~1.3.0`, an optional peer of `agents`. `agents`
+This subpath needs `@earendil-works/pi-ai@~1.4.0`, an optional peer of `agents`. `agents`
 takes no vendor package as a dependency, optional or otherwise. The surface is in beta
 and may change in a minor release. An unlisted `@cf/` id resolves with default metadata (a
 128k context window, 8192 output tokens, zero cost); pass overrides when you know better.

package/docs/routing.md

@@ -300,8 +300,6 @@ export default {
 
 For agent-specific initialization, use `getAgentByName` instead where you control exactly which agent receives the props.
 
-> **Note:** For `McpAgent`, props are automatically stored and accessible via `this.props`. See [MCP Servers](/mcp-servers) for details.
-
 ### Hooks
 
 `routeAgentRequest` supports hooks for intercepting requests before they reach agents:

package/docs/securing-mcp-servers.md

@@ -14,7 +14,7 @@ function createServer() {
   return new McpServer({ name: "authenticated-server", version: "1.0.0" });
 }
 
-const apiHandler = createMcpHandler(createServer);
+const mcpHandler = createMcpHandler(createServer);
 
 // Wrap with OAuth protection
 export default new OAuthProvider({
@@ -23,7 +23,12 @@ export default new OAuthProvider({
   clientRegistrationEndpoint: "/oauth/register",
 
   apiRoute: "/mcp", // Protected MCP endpoint
-  apiHandler: apiHandler, // Your MCP server
+  apiHandler: {
+    // OAuthProvider needs an object with a fetch method
+    fetch(request: Request, env: Env, ctx: ExecutionContext) {
+      return mcpHandler(request, env, ctx);
+    }
+  },
 
   defaultHandler: AuthHandler // Handles consent flow
 });

package/package.json

@@ -12,7 +12,7 @@
   "bin": {
     "agents": "./dist/cli.js"
   },
-  "version": "0.29.0",
+  "version": "0.30.1",
   "license": "MIT",
   "repository": {
     "directory": "packages/agents",
@@ -43,9 +43,10 @@
     "@ai-sdk/react": "^4.0.0",
     "@ai-sdk/valibot": "3.0.6",
     "@cloudflare/codemode": "^0.5.5",
-    "@earendil-works/pi-ai": "~1.3.0",
-    "@earendil-works/pi-durable": "~1.3.0",
-    "@earendil-works/pi-tui": "1.3.0",
+    "@earendil-works/chord": "~1.4.0",
+    "@earendil-works/pi-ai": "~1.4.0",
+    "@earendil-works/pi-durable": "~1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
     "@modelcontextprotocol/client": "2.3.1",
     "@modelcontextprotocol/conformance-v2": "npm:@modelcontextprotocol/conformance@0.2.0-alpha.12",
     "@modelcontextprotocol/sdk": "1.32.1",
@@ -71,8 +72,9 @@
     "@ai-sdk/provider": "^4.0.0",
     "@ai-sdk/react": "^3.0.0 || ^4.0.0",
     "@cloudflare/codemode": ">=0.5.0",
-    "@earendil-works/pi-ai": "~1.3.0",
-    "@earendil-works/pi-durable": "~1.3.0",
+    "@earendil-works/chord": "~1.4.0",
+    "@earendil-works/pi-ai": "~1.4.0",
+    "@earendil-works/pi-durable": "~1.4.0",
     "@modelcontextprotocol/client": "2.3.1",
     "@modelcontextprotocol/sdk": "1.32.1",
     "@modelcontextprotocol/server": "2.3.1",
@@ -98,6 +100,9 @@
     "@cloudflare/codemode": {
       "optional": true
     },
+    "@earendil-works/chord": {
+      "optional": true
+    },
     "@earendil-works/pi-ai": {
       "optional": true
     },