Docs: "All upstream SDK v2 handler options pass through" is not true for bus #2189

Summary

docs/agents/mcp-servers.md says every upstream SDK v2 handler option passes through to createMcpHandler. bus does not — it is omitted from the options type and throws. The sentence sent us looking for a supported path that isn't there.

What the docs say

docs/agents/mcp-servers.md, under createMcpHandler options:

All upstream SDK v2 handler options pass through. Use createLegacyMcpHandler for WorkerTransport, storage, session, and event-store options.

What actually happens

bus is an upstream SDK v2 handler option. In @modelcontextprotocol/server@2.0.0 — the version agents@0.22.0 pins as a peer — CreateMcpHandlerOptions declares bus?: ServerEventBus alongside responseMode, maxSubscriptions and keepAliveMs.

createStatelessMcpHandler omits it from its options type and rejects it:

// packages/agents/src/mcp/server/handler-stateless.ts L23, L141
export interface CreateStatelessMcpHandlerOptions extends Omit<SdkCreateMcpHandlerOptions, "bus">
throw new TypeError('createMcpHandler option "bus" is not exposed by the Agents SDK.')

This looks deliberate rather than accidental — handler-stateless.test.ts L669 is titled "rejects the upstream bus implementation detail" and asserts the throw. The code looks right; the docs sentence looks like the part that drifted.

The following sentence doesn't cover it either: bus is the subscriptions/listen change-event bus, not a WorkerTransport/storage/session/event-store option, so the createLegacyMcpHandler redirect doesn't apply. (eventStore is separately rejected as an SDK v1 option, which matches that sentence; bus has no equivalent pointer.)

Repro

agents@0.22.0, @modelcontextprotocol/server@2.0.0:

import { InMemoryServerEventBus, McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

const factory = () => new McpServer({ name: "repro", version: "1.0.0" });

createMcpHandler(factory, { keepAliveMs: 30_000 });   // OK
createMcpHandler(factory, { maxSubscriptions: 8 });   // OK
createMcpHandler(factory, { responseMode: "auto" });  // OK
createMcpHandler(factory, { onerror: () => {} });     // OK

createMcpHandler(factory, { bus: new InMemoryServerEventBus() });
// TypeError: createMcpHandler option "bus" is not exposed by the Agents SDK.

Suggested fix

Name the exception and point at the supported publish surface:

All upstream SDK v2 handler options pass through except bus, which is not exposed: the handler owns its own event bus and passing one throws. Use the handler's notify methods to publish change events. Use createLegacyMcpHandler for WorkerTransport, storage, session, and event-store options.

For context on how we hit it: we went looking for bus specifically, to fan subscriptions/listen notifications out beyond a single isolate. Knowing up front that the handler owns its bus, and that notify is the publish surface, would have saved the detour.

The suggested wording above is copy-pasteable if that helps.