[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

⚠️ 1 warning, 💡 1 suggestion found in commit b6a0f24.

👉 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 (1)

#### CR-af85e4f33f7b · Incorrect HTTP header semantics
- **File:** `src/content/docs/agents/tools/payments/index.mdx` line 39
- **Issue:** Line 39 states MPP 'adds the `WWW-Authenticate: Payment` and `Authorization: Payment` headers to HTTP `402` responses.' `Authorization` is an HTTP request header sent by the client on the retried request; it is not returned by the server in a 402 response.
- **Fix:** Correct the description: say `WWW-Authenticate: Payment` is added to the 402 response, and the client retries the request with an `Authorization: Payment` header.

### Suggestions (1)

#### CR-3b00ba364097 · Deprecated API used in new guide
- **File:** `src/content/docs/agents/tools/payments/mpp/accept-payments.mdx` line 137
- **Issue:** The MCP example builds a new server around McpAgent (`agents/mcp`), but the repository's McpAgent API reference states the class is deprecated and feature-frozen, and recommends migrating to `createMcpHandler` instead.
- **Fix:** Either migrate the MCP example to `createMcpHandler` or add a notice that `McpAgent` is deprecated and link to the migration guidance.

Code Review

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

Warnings (1)

File

Issue

agents/tools/payments/index.mdx line 39

Incorrect HTTP header semantics — Line 39 states MPP 'adds the WWW-Authenticate: Payment and Authorization: Payment headers to HTTP 402 responses.' Authorization is an HTTP request header sent by the client on the retried request; it is not returned by the server in a 402 response. Fix: Correct the description: say WWW-Authenticate: Payment is added to the 402 response, and the client retries the request with an Authorization: Payment header.

Suggestions (1)

File	Issue
agents/tools/payments/mpp/accept-payments.mdx line 137	Deprecated API used in new guide — The MCP example builds a new server around McpAgent (agents/mcp), but the repository's McpAgent API reference states the class is deprecated and feature-frozen, and recommends migrating to createMcpHandler instead. Fix: Either migrate the MCP example to createMcpHandler or add a notice that McpAgent is deprecated and link to the migration guidance.

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

[irvinebroque]

/bonk rebase branch off production

[ask-bonk]

Rebased successfully — the parv/mpp-agents-docs branch is now cleanly stacked on the latest production (8c3a2ab).

• Before: 9 PR commits on top of an older production base
• After: 9 rebased PR commits on top of 8c3a2ab (sync model catalog)

The branch previously contained 11 extra commits that were already in production due to a shallow clone during the first rebase attempt. After fetching the full production history and re-running the rebase, only the 9 actual PR commits were replayed — no conflicts.

github run

[irvinebroque]

/rebase

[parvahuja]

rebased!

[parvahuja]

i think still waiting on a 👍