Skip to content

[Agents] Document MCP servers with createMcpHandler only - #34525

Merged
mattzcarey merged 12 commits into
productionfrom
docs/agents-mcp-createmcphandler-only
Oct 27, 2026
Merged

mattzcarey merged 12 commits into
productionfrom
docs/agents-mcp-createmcphandler-only

Conversation

@mattzcarey

@mattzcarey mattzcarey commented Oct 22, 2026 •

Copy link
Copy Markdown
Member

The Agents MCP docs now show one way to build a server: a stateless createMcpHandler from agents/mcp/server with an MCP SDK v2 McpServer. McpAgent is now covered only by its own reference page (still marked deprecated) and Migrate to MCP SDK v2. The McpAgent RPC transport and this.props auth examples move from the transport and authorization pages into that reference page, so nothing is lost for existing users.

McpAgent has been deprecated since agents@0.20.0, but the docs still taught it next to createMcpHandler, including its RPC transport and this.props auth pattern.

  • Handler API: only createMcpHandler. Adds OAuthProvider wrapping, getMcpAuthContext() inside the factory for per-user tools, and the authContext option. Removes the createLegacyMcpHandler section and bumps the install to @modelcontextprotocol/server@2.3.1.
  • Transport: removes the legacy-lane section. The RPC transport (addMcpServer(name, binding)) is now documented on the MCP Client page. It is still supported but only reaches McpAgent, so the page recommends Streamable HTTP to a createMcpHandler server. The McpAgent reference keeps the server side (bindings, props, timeout).
  • Code Mode: merges codemode.mdx and build-codemode-openapi-mcp-server.mdx into Build a Code Mode MCP server, with redirects. codeMcpServer() and openApiMcpServer() still return SDK v1 servers, so the guide serves them with createLegacyMcpHandler.
  • Migrate to MCP SDK v2: withX402 and OpenAI Apps servers are listed as SDK v2-ready. Only Code Mode and mppx still need createLegacyMcpHandler. Pinned MCP versions are bumped to 2.3.1 / 1.32.1.
  • Tools / Authorization: rewrites the McpAgent examples as factory functions, including permission-based tool registration and state in bindings.
  • Remote MCP server guide: drops the approach table and the "templates still use McpAgent" note, and updates the GitHub template snippet.
  • x402: withX402 on an SDK v2 server served by createMcpHandler.
  • MPP: no McpAgent or Durable Object. mppx's Transport.mcpSdk() still needs SDK v1, so this one uses createLegacyMcpHandler per request.
  • ChatGPT app demo: SDK v2 and agents/mcp/server instead of the deprecated v1 createMcpHandler overload.
  • Smaller fixes in human-in-the-loop, routing, getCurrentAgent, securing MCP servers, the next-steps partial, and Agent Lee.

Every OAuthProvider example now passes { fetch } wrapping the handler. Passing the createMcpHandler function directly throws at startup, because OAuthProvider only accepts an ExportedHandler object or a WorkerEntrypoint class.

Left alone: Browser Run's Playwright MCP page (@cloudflare/playwright-mcp exports createMcpAgent).

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:

  • They type-check against agents@0.29, @modelcontextprotocol/server@2.3.1 and @cloudflare/workers-oauth-provider@1.2.4.
  • I ran them under wrangler dev. The auth server and resource server went through registration, consent (escaped client name, framing header, approve and deny), token and an authorized tools/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.

@github-actions github-actions Bot added product:workers Related to Workers product product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. product:agent-lee Related to Agent Lee product labels Oct 22, 2026
@cloudflare-docs-bot

cloudflare-docs-bot Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

AI Review

✅ Reviewed 407f7cd · 1 finding · incremental

👉 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

  • 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.

    const { access_token } = await tokenResponse.json<{ access_token: string }>();
Not reviewed (2)
  • src/content/docs/agents/model-context-protocol/codemode.mdx — deleted file
  • src/content/docs/agents/model-context-protocol/guides/build-codemode-openapi-mcp-server.mdx — deleted file
Resolved (10) · Dismissed (0)
  • Resolved: server is undefined in the stateful-tools example · Head tools.mdx block imports McpServer and declares const server = new McpServer({ name: "Counter" ... }) inside createServer() before server.registerTool(...); the example is complete and runnable, so the defect no longer exists.
  • Resolved: x402 example contradicts the MCP SDK v2 migration guide · Head migrate-to-mcp-sdk-v2.mdx 'Integration compatibility' now lists withX402 as accepting an SDK v2 McpServer served with createMcpHandler (from agents@0.27.0); the migration guide no longer contradicts the x402 page.
  • Resolved: Lowercase internet should be Internet · Head agent-api.mdx RPC transport section (lines 194-265) contains no 'without going over the public internet'; no added line in the base-to-head diff has the phrase.
  • Resolved: Marketing phrase perfect for · Head agent-api.mdx RPC section drops the old bullets; no added line contains 'perfect for' anywhere in the file.
  • Resolved: Heading begins with -ing verb · Heading at head is '### Read props from the caller' (imperative); 'Passing props to the MCP server' no longer exists.
  • Resolved: Heading begins with -ing verb · Heading at head is '### Configure the RPC transport timeout' (imperative); 'Configuring RPC transport server timeout' no longer exists.
  • Resolved: Heading begins with a verb ending in -ing · Heading at head (line 150) is '## Sign in through a third-party provider' — imperative form, no -ing verb.
  • Resolved: Directional word below in prose · Line 36 at head says 'as shown in Wrap an existing MCP server and Publish a large API with search and execute' — direct links replace the directional word 'below'.
  • Resolved: Heading begins with a gerund instead of an imperative verb · Heading at head is '## Use authentication context in tools' (imperative form); 'Using authentication context in tools' no longer exists.
  • Resolved: Description omits removal of the Code Mode MCP guide pages · Current PR description names the core change: 'Code Mode: merges codemode.mdx and build-codemode-openapi-mcp-server.mdx into Build a Code Mode MCP server, with redirects.' The omitted removals/rewrite are now described.
Commands
  • /review Run a review now.
  • /full-review Review the entire PR diff.
  • /disable-auto-review Stop automatic reviews.
  • /rebase Rebase against production.

@github-actions

github-actions Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Worker Preview URL: https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com
Worker Preview Deployment URL: https://027a2a0c.previews.developers.cloudflare.com

Files with changes (up to 15)

Original Link Updated Link
https://developers.cloudflare.com/agents/model-context-protocol/guides/securing-mcp-server/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/guides/securing-mcp-server/
https://developers.cloudflare.com/agents/model-context-protocol/protocol/authorization/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/protocol/authorization/
https://developers.cloudflare.com/agents/model-context-protocol/apis/handler-api/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/apis/handler-api/
https://developers.cloudflare.com/agents/model-context-protocol/protocol/transport/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/protocol/transport/
https://developers.cloudflare.com/agents/model-context-protocol/guides/build-codemode-mcp-server/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/guides/build-codemode-mcp-server/
https://developers.cloudflare.com/agents/model-context-protocol/protocol/tools/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/protocol/tools/
https://developers.cloudflare.com/agents/model-context-protocol/guides/build-codemode-openapi-mcp-server/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/guides/build-codemode-openapi-mcp-server/
https://developers.cloudflare.com/agents/model-context-protocol/guides/remote-mcp-server/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/guides/remote-mcp-server/
https://developers.cloudflare.com/agents/model-context-protocol/apis/agent-api/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/apis/agent-api/
https://developers.cloudflare.com/agents/model-context-protocol/codemode/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/codemode/
https://developers.cloudflare.com/agents/tools/payments/x402/charge-for-mcp-tools/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/tools/payments/x402/charge-for-mcp-tools/
https://developers.cloudflare.com/agents/tools/payments/mpp/accept-payments/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/tools/payments/mpp/accept-payments/
https://developers.cloudflare.com/agents/model-context-protocol/apis/client-api/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/apis/client-api/
https://developers.cloudflare.com/workers/demos/chatgpt-app/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/workers/demos/chatgpt-app/
https://developers.cloudflare.com/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2/ https://gh-docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com/agents/model-context-protocol/guides/migrate-to-mcp-sdk-v2/

@cloudflare-workers-and-pages

cloudflare-workers-and-pages Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://docs-agents-mcp-createmcphandler-only.previews.developers.cloudflare.com (commit 407f7cd)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status Deployment URL Commit Updated (UTC) See this deployment's details
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://11963d47.previews.developers.cloudflare.com 407f7cd 2026-10-27T10:26:30.993Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://bde58c48.previews.developers.cloudflare.com 500ab8c 2026-10-23T08:18:02.133Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://801b2183.previews.developers.cloudflare.com 0555b92 2026-10-22T17:15:57.163Z Visit the dashboard ↗
  • Build: In progress 🔵

View logs ↗
9c3a452 2026-10-22T16:54:31.093Z View logs ↗
  • Build: Failed ❌

View logs ↗
8021516 2026-10-22T16:53:35.531Z View logs ↗
  • Build: In progress 🔵

View logs ↗
707d572 2026-10-22T16:47:01.910Z View logs ↗
  • Build: In progress 🔵

View logs ↗
02fd30c 2026-10-22T16:42:56.176Z View logs ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://8abe9004.previews.developers.cloudflare.com d3c830b 2026-10-22T16:24:21.470Z Visit the dashboard ↗
  • Build: Success ✅
  • Deployment: Success ✅

View logs ↗
https://2ddbcaf6.previews.developers.cloudflare.com 2af5b92 2026-10-22T11:23:43.823Z Visit the dashboard ↗

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.
@mattzcarey
mattzcarey requested a review from a team as a code owner October 22, 2026 16:30
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.
@github-actions

Copy link
Copy Markdown
Contributor

This PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:

  • /agents/model-context-protocol/codemode/
  • /agents/model-context-protocol/guides/build-codemode-openapi-mcp-server/

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.
@mattzcarey

Copy link
Copy Markdown
Member Author

Triage of the AI review on 500ab8c:

  • C-1f701a91: skipping. tools.mdx declares const server = new McpServer(...) inside createServer() before server.registerTool(...), so the snippet is complete.
  • C-1b8f927c: the x402 page is correct. withX402 has accepted an SDK v2 McpServer since agents@0.27.0 (fix(x402): read paidTool payments from MCP SDK v2 handler context agents#2494). The migration guide was out of date, so the next commit updates it instead.
  • V-16da4b5e: fixed in the PR description.
  • S-*: all fixed in the next commit.

…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.
@mattzcarey
mattzcarey added this pull request to the merge queue Oct 27, 2026
Merged via the queue into production with commit 62ac2c7 Oct 27, 2026
13 checks passed
@mattzcarey
mattzcarey deleted the docs/agents-mcp-createmcphandler-only branch October 27, 2026 10:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

product:access product:agent-lee Related to Agent Lee product product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. product:changelog product:workers Related to Workers product size/xl

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants