Repository navigation
[Agents] Document MCP servers with createMcpHandler only - #34525
Conversation
AI Review✅ Reviewed 👉 Fix in your agent 👈Fix the following review findings in PR #34525 (https://github.com/cloudflare/cloudflare-docs/pull/34525).
Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification.
- If you disagree, explain why.
- If you need clarification before deciding, ask those questions.
- Then share your plan for which issues to tackle and in what order.
After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.
The comment must come before the commit because the next review reads PR comments.
## Code Review
- C-1133e4aa | src/content/docs/agents/model-context-protocol/guides/securing-mcp-server.mdx:274 | GitHub token exchange errors are never checked in the sign-in callback
`access_token` is destructured from the token response without checking `tokenResponse.ok` or a GitHub `error` field. When GitHub rejects the exchange (expired/replayed code, verifier mismatch, bad secret), `access_token` is `undefined`, the code still calls the GitHub API with `Authorization: Bearer undefined`, and `completeAuthorization()` then finishes with `userId: "undefined"` — a failed sign-in completes instead of failing closed. This path was not exercised by the PR's own testing, which stopped at the GitHub redirect and cookie-bound callback.
```txt
const { access_token } = await tokenResponse.json<{ access_token: string }>();
```Code Review
Not reviewed (2)
Resolved (10) · Dismissed (0)
Commands
|
🚀 Deploying Preview to Cloudflare 🚀Preview URL: https://docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com (commit 407f7cd)This URL reflects your latest Preview deploymentPreview Deployments by commit
|
Restore agent-api.mdx as the reference for existing McpAgent servers and move the McpAgent RPC transport and this.props auth examples there, so removing them from the transport and authorization pages loses nothing. Point the migration notes at it and drop the redirect.
Authorization now builds an OAuthAuthorizationServer and makes the MCP server an OAuthResourceServer around createMcpHandler, validated over a Service Binding. Securing MCP servers uses the library's consent and upstream sign-in helpers instead of hand-rolled CSRF and state code. Drop the context.http.authInfo claims (no provider release sets it) and fix the 1.x changelog's migration links.
Replace the hand-written escape helper with an API table for describeConsent, beginConsent, approveConsent, denyConsent and isConsentRemembered, and add one for beginUpstream, finishUpstream and tokenExchangeCallback. The library returns consent values but does not render HTML, so the page still escapes them.
Replace the April 2025 list with current guidance: keep tool definitions out of the context window with Code Mode on the client or server, use granular authorization with step-up, and declare accurate input and output schemas so strict clients accept your tools.
Fold the Code Mode MCP server patterns page and the search-and-execute guide into Build a Code Mode MCP server, which now covers choosing a pattern, wrapping an existing server, and publishing a large API with search and execute. Redirect the removed pages and update links.
|
This PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:
|
TypeScriptExample transpiles each block, so object-literal and route-handler fragments failed the build. Use plain ts blocks for them.
Replace fragments in the handler API, tools, transport, authorization, and securing pages with full modules wrapped in TypeScriptExample. The securing guide now has a complete authorization server with a consent page, one that signs users in with GitHub, and a resource server that checks scopes. Tool examples declare output schemas and return structuredContent. The x402 paidTool signature becomes a parameter table. Every example type-checks against agents 0.29, @modelcontextprotocol/server 2.3.1, and workers-oauth-provider 1.2.4, and was run under wrangler dev.
|
Triage of the AI review on
|
…h the migration guide - MCP Client: document addMcpServer(name, binding) as a supported transport that only reaches McpAgent, and recommend Streamable HTTP to a createMcpHandler server instead. - McpAgent: keep only the server side of the RPC transport (bindings, props, timeout). - Migrate to MCP SDK v2: withX402 and OpenAI Apps servers work with SDK v2; only Code Mode and mppx still need createLegacyMcpHandler. Bump pinned MCP versions to 2.3.1 / 1.32.1. - Style fixes from review: imperative headings, no directional words.
The Agents MCP docs now show one way to build a server: a stateless
createMcpHandlerfromagents/mcp/serverwith an MCP SDK v2McpServer.McpAgentis now covered only by its own reference page (still marked deprecated) and Migrate to MCP SDK v2. TheMcpAgentRPC transport andthis.propsauth examples move from the transport and authorization pages into that reference page, so nothing is lost for existing users.McpAgenthas been deprecated sinceagents@0.20.0, but the docs still taught it next tocreateMcpHandler, including its RPC transport andthis.propsauth pattern.createMcpHandler. AddsOAuthProviderwrapping,getMcpAuthContext()inside the factory for per-user tools, and theauthContextoption. Removes thecreateLegacyMcpHandlersection and bumps the install to@modelcontextprotocol/server@2.3.1.addMcpServer(name, binding)) is now documented on the MCP Client page. It is still supported but only reachesMcpAgent, so the page recommends Streamable HTTP to acreateMcpHandlerserver. TheMcpAgentreference keeps the server side (bindings, props, timeout).codemode.mdxandbuild-codemode-openapi-mcp-server.mdxinto Build a Code Mode MCP server, with redirects.codeMcpServer()andopenApiMcpServer()still return SDK v1 servers, so the guide serves them withcreateLegacyMcpHandler.withX402and OpenAI Apps servers are listed as SDK v2-ready. Only Code Mode andmppxstill needcreateLegacyMcpHandler. Pinned MCP versions are bumped to 2.3.1 / 1.32.1.McpAgentexamples as factory functions, including permission-based tool registration and state in bindings.McpAgent" note, and updates the GitHub template snippet.withX402on an SDK v2 server served bycreateMcpHandler.McpAgentor Durable Object.mppx'sTransport.mcpSdk()still needs SDK v1, so this one usescreateLegacyMcpHandlerper request.agents/mcp/serverinstead of the deprecated v1createMcpHandleroverload.getCurrentAgent, securing MCP servers, the next-steps partial, and Agent Lee.Every
OAuthProviderexample now passes{ fetch }wrapping the handler. Passing thecreateMcpHandlerfunction directly throws at startup, becauseOAuthProvideronly accepts anExportedHandlerobject or aWorkerEntrypointclass.Left alone: Browser Run's Playwright MCP page (
@cloudflare/playwright-mcpexportscreateMcpAgent).Merge after cloudflare/ai#680, which moves the GitHub OAuth template this guide quotes to
createMcpHandler. Repo-side docs: cloudflare/agents#2654.Every MCP example is a complete Worker in
TypeScriptExample:agents@0.29,@modelcontextprotocol/server@2.3.1and@cloudflare/workers-oauth-provider@1.2.4.wrangler dev. The auth server and resource server went through registration, consent (escaped client name, framing header, approve and deny), token and an authorizedtools/call. The GitHub sign-in example was checked up to the GitHub redirect and the cookie-bound callback. The handler and tools examples were run with real tool calls.