FAQ

General

What is MCPay?
MCPay is a payment layer for MCP servers and plain HTTP APIs. It uses HTTP 402 Payment Required with the x402 flow so clients (apps/agents/browsers) can pay per call and automatically retry to get the result. No subscriptions, no OAuth, no manual API keys.

Do I have to use MCP?
No. MCPay works great for plain HTTP endpoints. Using MCP adds niceties like tool discovery and pricing metadata for agent ecosystems.

Who is MCPay for?

• Providers (API/MCP owners) who want to price and monetize specific tools or routes.
• Integrators/Agents who need programmatic, per-call payments without human sign-ups.
• Builders who want the fastest path to ship paid MCP servers.

What’s the MCPay Registry?
A machine-readable catalog of MCP servers and their priced tools (analytics, recent payments, integration snippets). Browse the Registry at Servers.

What is MCPay Build?
A v0/Lovable-style builder that lets you describe tools, preview them live, read the generated code, price tools, and one-click deploy to GitHub + Vercel. Under the hood it uses an MCP server to orchestrate scaffolding, edits, previews, pricing, and deploy.

• Builder: mcpay.tech/build
• Build server page: mcpay.tech/servers/23e2ab26-7808-4984-855c-ec6a7dc97c3a

How it works

What is x402 and the 402 flow?

1. Client calls a protected route.
2. Service replies with 402 + price metadata (asset, amount, destination, memo, expiry).
3. The client (or MCPay proxy) pays on-chain.
4. The request is retried automatically with proof of payment.
5. The real response is returned. Usage and revenue events are emitted for analytics.

Is it “Stripe for agents”?
Similar goal (monetize usage) but different mechanics: no checkout, no subscriptions, keys optional. It’s pay-per-call that agents can handle end-to-end.

Can humans pay in a browser?
Yes. Wallet extensions or embedded wallets can perform the same 402 flow.

Pricing & Business

What pricing models can I use?

• Flat per call (simple & default).
• Per-tool / tiered pricing.
• Dynamic pricing via a /requirements step (e.g., compute cost, input size) before returning 402.

Can I price per token or by payload size?
Yes via dynamic requirements: compute price server-side and return it in the 402 metadata.

Do you take a cut?
You can route payments directly to your address. If you use managed wallets or optional platform features, platform fees may apply (configure per deployment).

Do you support revenue shares/affiliates?
Patterns like splits can be implemented by returning multiple accepted destinations or by off-chain rev-share accounting. (Roadmap: first-class splits.)

Payments, Wallets & Chains

Which chains/tokens are supported?
Common stablecoins (e.g., USDC) on supported networks (e.g., Base). The SDK is pluggable—you can add other EVM networks/tokens with proper decimals.

What wallets can the client use?

• EOA via a private key (server-side; dev only—secure in prod).
• CDP/embedded wallets for smoother UX.
• Browser extensions for human payers.

How do I cap client spend?
Use the SDK option maxPaymentValue (base units, e.g., 6 decimals for USDC) to hard-limit per-call on-chain value.

Are payments atomic with the call?
The flow is pay-then-retry. The memo (nonce) and expiry in price metadata prevent replay and stale payments.

Refunds & under-payments?
Providers typically handle refunds/credits app-side. Under-payments or wrong memo/expiry are rejected by the validator; clients receive a new 402 with fresh metadata.

Security & Reliability

How do you prevent replay attacks?
Price metadata includes an opaque memo/nonce and short expiry. Payments without the correct memo or after expiry are rejected.

Do you store private keys?

• SDK mode: keys stay where you run them (your server or client).
• Managed wallets (optional): keys are held by your chosen wallet provider; MCPay uses their APIs to sign/verify.

Rate limits & DoS protection?
The proxy includes lightweight rate limiting, header scrubbing, and optional caching for GETs. You should still add standard API defenses (WAF, throttles).

Idempotency?
Use the provided memo as part of your idempotency keys. The proxy retries only once after a confirmed payment.

SDK, CLI & DevEx

Which languages are supported?
JavaScript/TypeScript SDK + CLI today. Any language can integrate at the HTTP layer by handling 402 and sending an X-PAYMENT proof.

How do I integrate a paid server quickly?
Use the CLI as a stdio proxy:

npx mcpay server --urls https://mcpay.tech/mcp/<id> --api-key mcpay_XXXXX
# or use a wallet for on-chain payments:
npx mcpay server --urls https://mcpay.tech/mcp/<id> --private-key 0xYOUR_KEY

How do I define paid tools in code? Use createPaidMcpHandler and server.paidTool(name, price, schema, handler) in a Next.js Route Handler (or similar). See Quickstarts: Build and Monetize.

Can I call multiple paid servers at once? Yes—pass a comma-separated list to --urls in the CLI, or instantiate multiple transports in code.

Self-Hosting & Ops

Can I self-host? Yes. The reference app is Next.js. Common targets are Vercel and Docker/K8s. See Self-hosting docs for env, deploy, and observability.

What env vars do I need? Minimum depends on features, but expect MCPAY_API_KEY, DB/KV, optional wallet providers (e.g., CDP_*). See app/src/lib/gateway/env.ts.

Observability? MCPay emits usage/revenue events for dashboards. Add logs/metrics/traces (OpenTelemetry) per your platform.

HTTP (non-MCP) APIs

How do I monetize a plain HTTP route? Wrap it with the MCPay proxy. First call returns 402 + accepts. After payment is verified, the proxy retries the original request and returns the real response.

Do clients need to change much? Not really: they must handle one 402 round trip, pay, and retry (the SDK automates this).

Are wrapped services required to know about MCPay? No code changes are required in the upstream service.

Troubleshooting

I keep getting 402 even after paying. Check:

• expiry may have lapsed; request fresh price metadata.
• memo/nonce mismatches.
• Paid the wrong asset/chain or insufficient amount.
• Client’s maxPaymentValue is too low.
• Proxy cannot see confirmation yet (low gas or RPC lag).

“Payment accepted but upstream failed.” Your upstream returned an error on the retried call. Inspect proxy logs/analytics to confirm the payment and the upstream response; handle retries or issue a credit/refund.

Where do I find my server ID / MCP URL? In the Registry entry: /servers/<id>.

Can I test without spending much? Yes—use tiny prices + maxPaymentValue, and a low-value dev wallet. (For public networks, use small stablecoin balances/faucets where available.)

Legal & Service Wrapping

Are you affiliated with the APIs I wrap? No. MCPay is an integration layer. The services you wrap remain separate and subject to their own terms. Ensure your usage complies with those terms.