agents 0.30.0 → 0.31.0

package/docs/get-current-agent.md

@@ -142,9 +142,10 @@ context:
 
 ```typescript
 import { RpcTarget } from "cloudflare:workers";
+import { Agent, getCurrentAgent } from "agents";
 
 class HostCallbackBridge extends RpcTarget {
-  constructor(private agent: MyMcpAgent) {
+  constructor(private agent: MyAgent) {
     super();
   }
 
@@ -155,9 +156,9 @@ class HostCallbackBridge extends RpcTarget {
   }
 }
 
-export class MyMcpAgent extends McpAgent {
+export class MyAgent extends Agent {
   async handleSandboxCallback() {
-    const { agent } = getCurrentAgent<MyMcpAgent>();
+    const { agent } = getCurrentAgent<MyAgent>();
     // `agent` is available again.
   }
 }
@@ -166,10 +167,6 @@ export class MyMcpAgent extends McpAgent {
 Context restored this way has `connection`, `request`, and `email` unset. It
 is not tied to live client I/O.
 
-Server-initiated MCP requests (`elicitInput`, `createMessage`, and `listRoots`)
-on `McpAgent` do not require this indirection because the MCP transport retains
-its owning agent.
-
 ## API reference
 
 The agents package exports one main function for context management:

package/docs/harnesses/pi.md

@@ -1,10 +1,10 @@
 ---
-title: Pi harness (Beta)
+title: Pi harness
 pcx_content_type: get-started
-description: Host pi-durable sessions in a Durable Object with the beta PiHarness lifecycle capability. Connect a pi-ai model, add tools and skills, and keep sessions running across eviction.
+description: Host pi-durable sessions in a Durable Object with the PiHarness lifecycle capability. Connect a pi-ai model, add tools and skills, and keep sessions running across eviction.
 ---
 
-`PiHarness` hosts [pi-durable](https://github.com/earendil-works/pi/tree/main/packages/durable) in a Durable Object. It opens Pi over the object's SQLite database and connects Pi's sessions to the Agents SDK lifecycle, which wakes sessions with work after eviction. The API is in beta and may change.
+`PiHarness` hosts [pi-durable](https://github.com/earendil-works/pi/tree/main/packages/durable) in a Durable Object. It opens Pi over the object's SQLite database and connects Pi's sessions to the Agents SDK lifecycle, which wakes sessions with work after eviction.
 
 Pi owns everything about a run: the transcript, the inbox of steers and follow-ups, generation, tool calls, retries, and crash recovery. `PiHarness` supplies the storage and the wake. It does not provide a chat protocol or user interface. Your application chooses how clients reach sessions, such as WebSockets, HTTP, or RPC.
 
@@ -21,13 +21,14 @@ The three Pi packages are optional peer dependencies of `agents`, at `~1.4.0`. p
 `PiHarness` uses a factory function to construct Pi's `Harness` so it can be instantiated lazily:
 
 ```ts
+import { DurableObject } from "cloudflare:workers";
 import { createModels } from "@earendil-works/pi-ai/models";
 import { createRegistry, Harness } from "@earendil-works/pi-durable";
-import { Agent } from "agents";
 import { PiHarness } from "agents/harness/pi";
+import { Lifecycle } from "agents/lifecycle";
 import { createAI } from "agents/models/pi-ai";
 
-export class Assistant extends Agent<Env> {
+export class Assistant extends DurableObject<Env> {
   ai = createAI({ binding: this.env.AI });
   registry = createRegistry();
 
@@ -42,15 +43,12 @@ export class Assistant extends Agent<Env> {
       );
     },
     defaults: {
-      model: this.ai("@cf/zai-org/glm-4.7-flash"),
+      model: this.ai("@cf/zai-org/glm-5.3-flash"),
       thinkingLevel: "low"
     }
   });
 
-  constructor(ctx: DurableObjectState, env: Env) {
-    super(ctx, env);
-    this.lifecycle.use(this.harness);
-  }
+  lifecycle = Lifecycle.install(this).use(this.harness);
 
   async ask(prompt: string) {
     return (await this.harness.prompt(prompt)).text;
@@ -58,6 +56,8 @@ export class Assistant extends Agent<Env> {
 }
 ```
 
+`PiHarness` is a Lifecycle capability, so it runs on a plain Durable Object. `Lifecycle.install(this)` gives the object its startup, alarms and job queue, and `.use(this.harness)` installs the harness on it. The object needs a SQLite migration in your Wrangler configuration, like any Durable Object that uses SQLite storage. To use it from an `Agent`, which already has a lifecycle, call `this.lifecycle.use(this.harness)` in the constructor instead.
+
 | Option     | What it is                                                                                                                                                                                                                                                                                                                          |
 | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `harness`  | Required. Receives `{ storage, context, onWake }` and returns Pi's `Harness`, usually from `Harness.open`. Pass `onWake` to `Harness.open`, so the object can hibernate while Pi's tasks sleep (see [How recovery works](#how-recovery-works)). Models, the registry, `settings`, `env` and `onReport` are all yours to build here. |
@@ -149,7 +149,7 @@ harness: async ({ storage, context, onWake }) => {
   this.registry.install({
     name: "browser",
     tools: [
-      browserTool({ ctx: this.ctx, browser: this.browser, loader: this.env.LOADER })
+      browserTool({ browser: this.browser, loader: this.env.LOADER })
     ]
   });
   return Harness.open(
@@ -162,7 +162,7 @@ harness: async ({ storage, context, onWake }) => {
 readonly lifecycle = Lifecycle.install(this).use(this.browser).use(this.harness);
 ```
 
-It needs a `browser` binding, a `LOADER` Worker Loader binding, and `export { CodemodeRuntime } from "@cloudflare/codemode"` from the Worker entry. Screenshots come back as images, and each conversation works in its own tab. Refer to [Persistent browser](../browse-the-web.md#persistent-browser) for how it behaves.
+It needs a `browser` binding, a `LOADER` Worker Loader binding, and `@cloudflare/codemode` installed (only until the deprecated codemode browser APIs are removed from `agents/browser`). Screenshots come back as images, and each conversation works in its own tab. Refer to [Persistent browser](../browse-the-web.md#persistent-browser) for how it behaves.
 
 ## Work with sessions
 
@@ -174,7 +174,7 @@ const { text } = await this.harness.prompt("What is 47 × 19?");
 
 // Another session, on a cheaper model.
 const session = await this.harness.sessions.create();
-await session.setModel(this.ai("@cf/zai-org/glm-4.7-flash"));
+await session.setModel(this.ai("@cf/zai-org/glm-5.3-flash"));
 
 // Durable once it returns; the same operation id twice is one submission.
 const receipt = await session.submit("Summarize the latest report", {
@@ -183,20 +183,20 @@ const receipt = await session.submit("Summarize the latest report", {
 const result = await session.wait(receipt.operationId);
 ```
 
-| Call                                              | What it does                                                                                                                                                                                                                                                                                                                         |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `prompt(input)`                                   | Submits and waits: the answer, and the transcript after it.                                                                                                                                                                                                                                                                          |
-| `submit(input, { operationId, whenBusy, entry })` | Hands the input to Pi and returns as soon as Pi has saved it, without waiting for the model. If the session is already working, the input waits until that work finishes. With `whenBusy: "steer"`, it joins the running work instead, after the current round of tool calls. `entry` records where the input came from (see below). |
-| `wait(operationId, signal?)`                      | The operation's result once Pi settles it. Aborting `signal` stops only the wait, not the work.                                                                                                                                                                                                                                      |
-| `steer(input)`                                    | `submit` with `whenBusy: "steer"`.                                                                                                                                                                                                                                                                                                   |
-| `abort(operationId?)`                             | Withdraws a queued operation, or with no id, stops everything running in the session.                                                                                                                                                                                                                                                |
-| `pending()`                                       | Operations Pi has not settled yet: queued, part of the running work, or `parked` (see [How recovery works](#how-recovery-works)).                                                                                                                                                                                                    |
-| `retry()`                                         | Runs again the tasks Pi's restart limit parked in the session's work. Resolves `false` when nothing was parked.                                                                                                                                                                                                                      |
-| `messages()`                                      | Pi's transcript entries since the newest reset.                                                                                                                                                                                                                                                                                      |
-| `events()`                                        | Pi's agent events: a `snapshot`, then one batch per commit.                                                                                                                                                                                                                                                                          |
-| `reset(handoff?)`                                 | Starts a new context, optionally from a handoff note.                                                                                                                                                                                                                                                                                |
-| `setModel(model)`                                 | Changes this session's model.                                                                                                                                                                                                                                                                                                        |
-| `busy()`                                          | Whether a run is going.                                                                                                                                                                                                                                                                                                              |
+| Call                                              | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prompt(input)`                                   | Submits and waits: the answer, and the transcript after it.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `submit(input, { operationId, whenBusy, entry })` | Hands the input to Pi and returns as soon as Pi has saved it, without waiting for the model. If the session is already working, the input waits until that work finishes. With `whenBusy: "steer"`, it joins the running work instead, after the current round of tool calls. With `whenBusy: "reject"`, it is not admitted: `submit` rejects with Pi's `ConversationBusy` and nothing is saved, so the same `operationId` can be submitted again later. `entry` records where the input came from (see below). |
+| `wait(operationId, signal?)`                      | The operation's result once Pi settles it. Aborting `signal` stops only the wait, not the work.                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `steer(input)`                                    | `submit` with `whenBusy: "steer"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `abort(operationId?)`                             | Withdraws a queued operation, or with no id, stops everything running in the session.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `pending()`                                       | Operations Pi has not settled yet: queued, part of the running work, or `parked` (see [How recovery works](#how-recovery-works)).                                                                                                                                                                                                                                                                                                                                                                               |
+| `retry()`                                         | Runs again the tasks Pi's restart limit parked in the session's work. Resolves `false` when nothing was parked.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `messages()`                                      | Pi's transcript entries since the newest reset.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `events()`                                        | Pi's agent events: a `snapshot`, then one batch per commit.                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `reset(handoff?)`                                 | Starts a new context, optionally from a handoff note.                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `setModel(model)`                                 | Changes this session's model.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `busy()`                                          | Whether a run is going.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 
 `harness.prompt()`, `submit()`, `wait()`, `abort()`, `retry()`, `messages()` and `pending()` act on the root session, or on `{ session }`. `harness.sessions` has `create()`, `fork(from)`, `get(id)` and `list()`, which includes sessions subagents created. `ROOT_SESSION` is the root's id.
 
@@ -246,7 +246,7 @@ With `keep`, the kept inputs are not work to Pi: its `wake()` counts tasks, not
 
 ## How recovery works
 
-The harness schedules one lifecycle job, driven by Pi's `wake()`. While Pi has work running, the job waits on it and refreshes itself as a heartbeat. While Pi's tasks sleep, such as a retry backoff, the job is due when the first one wakes. Pi says when through the `onWake` the factory passes to `Harness.open`, and sets no in-memory timer of its own, so the object can hibernate until then. Without `onWake` the harness still works, but Pi's timer keeps the object in memory, and billed, while a task sleeps, and the harness logs a warning. When Pi has nothing to do, the job completes. If the object is evicted or crashes, the job is still due, so its alarm restarts the object. Pi reopens its stored state and resumes the session's work: a replay-safe tool call runs again, and an unsafe one is reported to the model as interrupted.
+The harness schedules one lifecycle job, driven by Pi's `wake()`. While Pi has work running, the job waits on it and refreshes itself as a heartbeat. While Pi's tasks sleep, such as a retry backoff, the job is due when the first one wakes. Pi says when through the `onWake` the factory passes to `Harness.open`, and sets no in-memory timer of its own, so the object can hibernate until then. A task that sleeps while other work runs, such as a compaction retry during a generation, is resumed from the job's wait when it is due. Without `onWake` the harness still works, but Pi's timer keeps the object in memory, and billed, while a task sleeps, and the harness logs a warning. When Pi has nothing to do, the job completes. If the object is evicted or crashes, the job is still due, so its alarm restarts the object. Pi reopens its stored state and resumes the session's work: a replay-safe tool call runs again, and an unsafe one is reported to the model as interrupted.
 
 A task that keeps crashing the object would restart it forever, so Pi parks a task cut off by a crash or eviction `settings.restartLimit` times in a row (default 5) without progress. A parked task is not work: the job completes and the object can hibernate. Its operations show as `parked` in `pending()`, and `wait()` keeps waiting. If your factory passes `onReport` to `Harness.open`, Pi reports it there as `task_parked`. Once you have dealt with the cause, `session.retry()` runs it again and wakes the harness; `session.abort()` gives up on it instead.
 

package/docs/human-in-the-loop.md

@@ -32,7 +32,6 @@ Agents SDK supports multiple human-in-the-loop patterns. Choose based on your us
 | OpenAI Agents SDK      | `needsApproval`       | Using OpenAI's agent SDK with conditional approval | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop)   |
 | Client-side tools      | `onToolCall`          | Tools that need browser APIs or user interaction   | Pattern below                                                                                                  |
 | Stateless servers      | Stateless Elicitation | Current MCP tools requesting structured input      | [examples/mcp-elicitation-mrtr/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr) |
-| Legacy servers         | Legacy Elicitation    | Existing sessionful MCP deployments                | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)           |
 
 ### Decision Guide
 
@@ -40,7 +39,7 @@ Agents SDK supports multiple human-in-the-loop patterns. Choose based on your us
 Is this part of a multi-step workflow?
 ├── Yes → Use Workflow Approval (waitForApproval)
 └── No → Are you building an MCP server?
-         ├── Yes → Use MCP Elicitation (elicitInput)
+         ├── Yes → Use MCP Elicitation (inputRequired)
          └── No → Is this an AI chat interaction?
                   ├── Yes → Does the tool need browser APIs?
                   │        ├── Yes → Use onToolCall (client-side execution)
@@ -460,7 +459,7 @@ See the complete example: [openai-sdk/human-in-the-loop/](https://github.com/clo
 
 ### MCP Elicitation
 
-**Stateless Elicitation** uses multi-round-trip requests (MRTR). A handler returns `inputRequired(...)`; the client gathers the requested input and retries with SDK-managed state. No Worker remains suspended while the user responds.
+MCP servers built with `createMcpHandler` use multi-round-trip requests (MRTR) for elicitation. A handler returns `inputRequired(...)`; the client gathers the requested input and retries with SDK-managed state. No Worker remains suspended while the user responds.
 
 ```typescript
 import {
@@ -517,8 +516,6 @@ The MCP client renders the JSON Schema form and the original operation remains p
 
 See the [Stateless Elicitation example](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr).
 
-**Legacy Elicitation** in existing Legacy deployments uses pushed `elicitation/create` requests over a stateful transport. See the explicitly legacy [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation) example when retaining `McpAgent` or `createLegacyMcpHandler` with `WorkerTransport`.
-
 ## State Patterns for Approvals
 
 Track pending approvals in agent state for UI rendering and persistence:
@@ -640,10 +637,9 @@ async submitForApproval(request: ApprovalRequest): Promise<string> {
 | AIChatAgent tools     | [guides/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/guides/human-in-the-loop)           | Chat tool approval with needsApproval + onToolCall |
 | OpenAI Agents SDK     | [openai-sdk/human-in-the-loop/](https://github.com/cloudflare/agents/tree/main/openai-sdk/human-in-the-loop)   | Conditional tool approval with modal               |
 | Stateless Elicitation | [examples/mcp-elicitation-mrtr/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation-mrtr) | Stateless multi-round input                        |
-| Legacy Elicitation    | [examples/mcp-elicitation/](https://github.com/cloudflare/agents/tree/main/examples/mcp-elicitation)           | Stateful pushed input requests                     |
 
 For detailed API documentation, see:
 
 - [Workflows](./workflows.md) - `waitForApproval()`, `approveWorkflow()`, `rejectWorkflow()`
-- [MCP Servers](./mcp-servers.md) - `inputRequired()` and legacy `elicitInput()`
+- [MCP Servers](./mcp-servers.md) - `inputRequired()` elicitation
 - [Callable Methods](./callable-methods.md) - `@callable()` decorator for approval endpoints

package/docs/index.md

@@ -49,7 +49,7 @@ The Lifecycle runs startup, routes requests to capabilities, and owns the object
 
 ## Harnesses
 
-- [Pi harness (Beta)](./harnesses/pi.md) - Host pi-durable sessions in a Durable Object with durable storage and lifecycle wakeups
+- [Pi harness](./harnesses/pi.md) - Host pi-durable sessions in a Durable Object with durable storage and lifecycle wakeups
 - [Think harness (Experimental)](./harnesses/think.md) - Run Think's agent loop as a Lifecycle capability, with transcripts in Sessions, output in Streams, and turns that survive eviction
 - [Think (Experimental)](https://github.com/cloudflare/agents/blob/main/docs/think/index.md) - Opinionated chat agent with built-in memory, tools, and streaming. Extends `Think`, which builds on `Agent`.
 
@@ -136,12 +136,12 @@ Building your own harness? Sessions stores the conversation, Streams holds durab
 - TODO: [AI SDK Integration](./ai-sdk.md) - Using Vercel AI SDK with agents
 - TODO: [TanStack Integration](./tanstack.md) - Using TanStack AI with agents
 - TODO: [Using AI Models](./using-ai-models.md) - OpenAI, Anthropic, Workers AI, and other providers
-- [Models (Experimental)](./models.md) - `createAI` — one AI SDK provider for Workers AI and third-party catalog models, same string space
-- [Models for pi-ai (Beta)](./models-pi-ai.md) - `createAI` for pi-ai: Workers AI ids and third-party models through AI Gateway, as a pi-ai provider
+- [Models](./models.md) - `createAI` — one AI SDK provider for Workers AI and third-party catalog models, same string space
+- [Models for pi-ai](./models-pi-ai.md) - `createAI` for pi-ai: Workers AI ids and third-party models through AI Gateway, as a pi-ai provider
 - [Context (Experimental)](./context.md) - System-prompt blocks, frozen prompts, writable/searchable/loadable providers, and their tools
 - [Workspace (Experimental)](https://github.com/cloudflare/agents/blob/main/docs/shell/index.md) - Durable virtual filesystem backed by SQLite + R2
 - [Codemode (Experimental)](./codemode.md) - LLM-generated executable code for tool orchestration
-- [Browse the Web (Experimental)](./browse-the-web.md) - Full CDP access for web inspection, scraping, and debugging
+- [Browse the Web](./browse-the-web.md) - Full CDP access for web inspection, scraping, and debugging
 - [Search the Web (Beta)](./search-the-web.md) - A `websearch` tool over Cloudflare's Web Search API for the pi harness, the AI SDK, and TanStack AI
 - [Fetch the Web (Beta)](./fetch-the-web.md) - A `web_fetch` tool that reads a URL as Markdown, JSON, or text, with a host-controlled URL policy, for the pi harness, the AI SDK, TanStack AI, and Think
 - TODO: [Cloudflare Sandboxes](./sandboxes.md) - Isolated environments for coding agents, ffmpeg, and heavy compute
@@ -149,10 +149,10 @@ Building your own harness? Sessions stores the conversation, Streams holds durab
 
 ## MCP (Model Context Protocol)
 
-- [Creating MCP Servers](./mcp-servers.md) - Build MCP servers with `McpAgent`
+- [Creating MCP Servers](./mcp-servers.md) - Build stateless MCP servers with `createMcpHandler`
 - [Securing MCP Servers](./securing-mcp-servers.md) - OAuth and authentication for MCP
 - [Connecting to MCP Servers](./mcp-client.md) - `MCPClientManager` on a Durable Object, or `addMcpServer()` on an Agent
-- [MCP Transports](./mcp-transports.md) - Transport options: Streamable HTTP, SSE, and RPC
+- [MCP Transports](./mcp-transports.md) - Streamable HTTP on the server, and the transports an Agent can connect with
 
 ## Operations
 

package/docs/mcp-client.md

@@ -51,19 +51,6 @@ callback URL to `registerServer()` and route that request to the same named
 Durable Object. The manager persists the URL and only intercepts a callback
 whose origin and pathname match it.
 
-An HTTP-only manager does not need `env`. Pass the Durable Object environment
-when the catalog can contain RPC servers so persisted binding names can be
-resolved after a wake:
-
-```ts
-readonly mcp = new MCPClientManager("my-object", "1.0.0", {
-  env: this.env
-});
-```
-
-If an RPC row exists without `env`, startup logs a warning identifying the
-server and does not recreate that connection.
-
 `Agent` installs this same capability object directly. Existing `this.mcp`,
 `addMcpServer()`, `removeMcpServer()`, and `getMcpServers()` APIs remain
 available.
@@ -76,6 +63,8 @@ Install the exact MCP client peer used by this Agents release:
 pnpm add agents @modelcontextprotocol/client@2.3.1
 ```
 
+The MCP client does not need `@modelcontextprotocol/sdk` or `@modelcontextprotocol/server`. Those packages are optional peers used only by the MCP server APIs.
+
 ```typescript
 import { Agent } from "agents";
 
@@ -188,7 +177,7 @@ These options are persisted and used when reconnecting after hibernation or afte
 
 ### Protocol negotiation and elicitation
 
-Agents uses the MCP v2 client and automatically negotiates the protocol version for every connection. It uses `server/discover` with Stateless servers and falls back to the `initialize` handshake on the same connection for Legacy Streamable HTTP, SSE, and RPC servers.
+Agents uses the MCP v2 client and automatically negotiates the protocol version for every connection. It uses `server/discover` with Stateless servers and falls back to the `initialize` handshake on the same connection for Legacy Streamable HTTP and SSE servers.
 
 MCP servers can request input from the client during `callTool`, `getPrompt`, or `readResource`. Stateless Elicitation returns an `input_required` result and completes through MRTR: the MCP SDK invokes the configured `elicitation/create` handler, sends its response, and continues the original request. Agents does not expose an intermediate continuation; the original call stays pending while human input is collected and eventually resolves to the ordinary tool, prompt, or resource result. Legacy Elicitation on Legacy servers continues to use pushed `elicitation/create` requests. Both generations share the same handlers.
 
@@ -243,8 +232,6 @@ MCP server URLs are validated before connection to prevent Server-Side Request F
 
 Loopback development URLs such as `localhost`, `127.0.0.1`, and `::1` are allowed.
 
-If you need to connect to another internal MCP server, use the [RPC transport](./mcp-transports.md) with a Durable Object binding instead of HTTP.
-
 ### Return Value
 
 `addMcpServer()` returns the connection state:
@@ -666,17 +653,6 @@ async addMcpServer(
   | { id: string; state: "authenticating"; authUrl: string }
 >
 
-// RPC transport (Durable Object binding — no HTTP overhead)
-async addMcpServer(
-  name: string,
-  binding: DurableObjectNamespace,
-  options?: {
-    props?: Record<string, unknown>; // passed to the McpAgent's onStart(props)
-    client?: ClientOptions;
-    retry?: RetryOptions;
-  }
-): Promise<{ id: string; state: "ready" }>
-
 // Legacy signature (still supported)
 async addMcpServer(
   name: string,
@@ -689,7 +665,7 @@ async addMcpServer(
 
 Add and connect to an MCP server. Throws if connection or discovery fails.
 
-`callbackHost` is automatically derived from the incoming HTTP request or WebSocket connection URI — you almost never need to set it explicitly. It is only needed when the auto-detected host does not match your desired OAuth callback origin (for example, behind a reverse proxy). For RPC transport, pass a `DurableObjectNamespace` binding instead of a URL. See [MCP Transports](./mcp-transports.md) for details.
+`callbackHost` is automatically derived from the incoming HTTP request or WebSocket connection URI — you almost never need to set it explicitly. It is only needed when the auto-detected host does not match your desired OAuth callback origin (for example, behind a reverse proxy). See [MCP Transports](./mcp-transports.md) for the transport options.
 
 Calling `addMcpServer` is idempotent when both the server name **and** URL match an existing active connection — the existing connection is returned without creating a duplicate. This makes it safe to call in `onStart()` without worrying about duplicate connections on restart.