Repository navigation
docs(mcp): document servers with createMcpHandler only - #2654
mattzcarey wants to merge 2 commits into
Conversation
Remove McpAgent, WorkerTransport, createLegacyMcpHandler, and the McpAgent RPC transport from the MCP docs. Servers are documented as stateless createMcpHandler handlers, with state in bindings or an Agent, OAuthProvider auth, and inputRequired elicitation. mcp-servers.md keeps one link to the SDK v2 migration guide for existing McpAgent servers.
|
|
✅ agents import sizes: no significant changes ( |
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| # Creating MCP Servers | ||
|
|
||
| This guide covers the different ways to create MCP servers with the Agents SDK and helps you choose the right approach. | ||
| Build an MCP server on Workers with `createMcpHandler` from `agents/mcp/server` and an MCP SDK v2 `McpServer`. The handler is stateless: every request gets a fresh server from your factory, so there is no Durable Object, session, or WebSocket to manage. It serves draft MCP `2026-07-28` and stateless 2025-era clients from the same endpoint. |
There was a problem hiding this comment.
🔍 Verify the upstream documentation update
The documentation rules require matching updates in cloudflare/cloudflare-docs. Confirm these MCP pages are ported; this repository has no automated sync.
Was this helpful? React with 👍 or 👎 to provide feedback.
| const userId = String(getMcpAuthContext()?.props.userId ?? "anonymous"); | ||
| const notes = await getAgentByName(env.Notes, userId); | ||
| const count = await notes.add(note); | ||
| return { content: [{ type: "text", text: `You have ${count} notes` }] }; |
There was a problem hiding this comment.
🟨 Anonymous clients share private notes state
Without OAuth, getMcpAuthContext() is empty, so every caller writes to the same Notes agent. Each caller receives a count that includes other callers' notes.
Was this helpful? React with 👍 or 👎 to provide feedback.
agents
@cloudflare/ai-chat
@cloudflare/codemode
hono-agents
@cloudflare/shell
@cloudflare/think
@cloudflare/voice
@cloudflare/worker-bundler
commit: |
OAuthProvider only accepts an ExportedHandler object or a WorkerEntrypoint class, so passing the handler function directly throws at startup.
| - All MCP session data stays within the EU | ||
| - User data processed by your tools remains in the EU | ||
| - State stored in the Durable Object's storage API stays in the EU | ||
| `OAuthProvider` needs an object with a `fetch` method, so wrap the handler as shown. Passing the handler function directly throws at startup. |
There was a problem hiding this comment.
🔍 OAuth startup claim conflicts with callable handler
createMcpHandler returns a function with a fetch property, and the authenticated example passes it directly to OAuthProvider. The claim that this throws at startup needs verification against the provider's runtime behavior.
Was this helpful? React with 👍 or 👎 to provide feedback.
1 participant
The MCP docs now show one way to build a server: a stateless
createMcpHandlerfromagents/mcp/serverwith an SDK v2McpServer.McpAgent,WorkerTransport,createLegacyMcpHandlerand theMcpAgentRPC transport are gone from the docs. Docs only, no code changes.McpAgenthas been deprecated since 0.20.0, butmcp-servers.mdstill walked through it next tocreateMcpHandleras if you had to choose between them.mcp-servers.mdis rewritten aroundcreateMcpHandler: install, a minimal server, keeping state in bindings or an Agent (getAgentByNamefrom a tool), handler options, Origin checks, notifications,OAuthProviderauth withgetMcpAuthContext(),inputRequiredelicitation, and 2025-era clients. One short section links existingMcpAgentusers to the SDK v2 migration guide.mcp-transports.mdcovers Streamable HTTP on the server and theauto/streamable-http/sseclient options. TheMcpAgentSSE, auto and RPC transport sections are removed.mcp-client.md,human-in-the-loop.md,get-current-agent.md,routing.md,index.mdand the package README lose theirMcpAgent, RPC transport and Legacy Elicitation references.I type-checked the new snippets in
mcp-servers.md(bindings, theNotesAgent, auth) against the built package.Overlaps with #2634 in
mcp-servers.md,mcp-transports.md,mcp-client.mdand the README; I'll rebase whichever merges second.