[Agents] Improve MPP payment guides

[parvahuja]

Summary

Restructures the Machine Payments Protocol (MPP) documentation around Cloudflare tasks while keeping the protocol overview close to the original page.

• Updates the overview with payment-method independence, charge, session, and subscription intents, x402 compatibility, and links to the Cloudflare how-to guides.
• Keeps the existing HTTP content guide under Agentic Payments and links to it wherever mpp-proxy is referenced.
• Shows how to accept MPP payments from a Worker route or an McpAgent tool.
• Shows how a Cloudflare Agent pays HTTP services and MCP tools with mppx.
• Removes Lightning and Bitcoin references and minimizes payment-method-specific prose.

The implementation pages remain how-to content. The examples use imperative steps, Cloudflare components, root-relative internal links, TOML Wrangler configuration, and scoped automatic-payment policies.

Depends on cloudflare/mpp-proxy#30, which restores the proxy's advertised charge-only flow.

Before	After
payments/mpp.mdx	payments/mpp/index.mdx
No dedicated server guide	payments/mpp/accept-payments.mdx
No dedicated buyer guide	payments/mpp/pay-from-agents-sdk.mdx

Redirects preserve the existing MPP URLs.

Validation

• Deployed fresh test Workers from the guides.
• Confirmed an unpaid Worker route returns 402 Payment Required and WWW-Authenticate: Payment.
• Completed a nonzero testnet payment from an Agent to the Worker route and received Payment-Receipt.
• Called free and paid McpAgent tools from an Agent; the paid call completed a nonzero testnet payment and returned an MPP Receipt.
• Confirmed the fixed mpp-proxy returns 200 from /__mpp/health and a charge challenge from unpaid /__mpp/protected.
• pnpm run check
• pnpm run format:core:check
• pnpm exec tsm bin/validate-redirects.ts
• RUN_LINK_CHECK=true pnpm run build (8,695 pages; all internal links valid)
• Rendered the MPP pages locally and checked the affected pages for browser-console errors.

Documentation checklist

• The change adheres to the documentation style guide.
• If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.
• Files which have changed name or location have been allocated redirects.

[cloudflare-docs-bot]

Review

⚠️ 2 warnings found in commit 0566dd2.

👉 Fix in your agent 👈

Fix the following review findings in PR #32185 (https://github.com/cloudflare/cloudflare-docs/pull/32185).

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 (e.g. the fix requires disproportionate effort for minimal benefit,
  or the finding is factually incorrect), 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 — the bot reads PR comments when a new
push triggers a review, so skip comments posted after the push will be missed.

---

## Code Review

### Warnings (2)

#### CR-1f8e17216981 · Unhandled MCP OAuth state
- **File:** `src/content/docs/agents/tools/payments/mpp/pay-from-agents-sdk.mdx` line 116
- **Issue:** `const { id } = await this.addMcpServer(...)` only destructures `id` and ignores the returned `state` field. The Agents MCP client API returns either `{ id, state: "ready" }` or `{ id, state: "authenticating", authUrl }`; for OAuth-required servers the connection is not usable until the user authorizes via `authUrl`.
- **Fix:** Check the returned `state` and, when it is `"authenticating"`, redirect the user to `authUrl` (or handle OAuth) before calling `waitForConnections()` and accessing `this.mcp.mcpConnections[id].client`.

#### CR-0c9fbccbd032 · Unvalidated MCP connection lookup
- **File:** `src/content/docs/agents/tools/payments/mpp/pay-from-agents-sdk.mdx` line 122
- **Issue:** `this.mcp.mcpConnections[id].client` is dereferenced without first checking that the connection exists and is ready. If `addMcpServer()` fails, the connection is still authenticating, or `waitForConnections()` did not succeed, `this.mcp.mcpConnections[id]` may be undefined or missing a usable `client`.
- **Fix:** Verify the connection state using `this.getMcpServers()` or a null check on `this.mcp.mcpConnections[id]` before wrapping the client with `McpClient.wrap`.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

Warnings (2)

File	Issue
agents/tools/payments/mpp/pay-from-agents-sdk.mdx line 116	Unhandled MCP OAuth state — const { id } = await this.addMcpServer(...) only destructures id and ignores the returned state field. The Agents MCP client API returns either { id, state: "ready" } or { id, state: "authenticating", authUrl }; for OAuth-required servers the connection is not usable until the user authorizes via authUrl. Fix: Check the returned state and, when it is "authenticating", redirect the user to authUrl (or handle OAuth) before calling waitForConnections() and accessing this.mcp.mcpConnections[id].client.
agents/tools/payments/mpp/pay-from-agents-sdk.mdx line 122	Unvalidated MCP connection lookup — this.mcp.mcpConnections[id].client is dereferenced without first checking that the connection exists and is ready. If addMcpServer() fails, the connection is still authenticating, or waitForConnections() did not succeed, this.mcp.mcpConnections[id] may be undefined or missing a usable client. Fix: Verify the connection state using this.getMcpServers() or a null check on this.mcp.mcpConnections[id] before wrapping the client with McpClient.wrap.

Conventions

_{No convention issues found.}

Style Guide Review

_{No style-guide issues found.}

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review	Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.
/rebase	Rebases the PR branch against production. On conflict, attempts to resolve automatically using AI. Stops with an explanation if confidence is not high enough.

[irvinebroque]

/bonk please review

[ask-bonk]

This is a clear, well-structured restructure. The new how-to guides fill meaningful gaps in the MPP docs.

I agree with the three warnings from the bot review (bold link text, unhandled MCP OAuth state, and unvalidated connection lookup) and have two additional minor style notes below.

Please address the bot findings before merging.

[ask-bonk]

Review submitted successfully at cloudflare/cloudflare-docs/pull/32185.

Summary of findings:

• Agreed with the bot’s 3 warnings and asked the author to address them before merging:

  1. accept-payments.mdx line 20 — bold link text around mpp-proxy violates the style guide.
  2. pay-from-agents-sdk.mdx line 116 — addMcpServer() can return an OAuth authUrl that must be handled.
  3. pay-from-agents-sdk.mdx line 122 — mcpConnections[id] should be null-checked before dereferencing .client.

• Added 2 minor style/consistency notes:

  • payments/index.mdx card title “Pay with MPP” doesn’t match the target page title “Pay from the Agents SDK.”
  • Inconsistent capitalization in the payment flow steps on payments/index.mdx (Challenge vs. credential vs. receipt).

github run