Connect MCP to an x402 API marketplace

Connect your agent runtime to https://marketplaceforaiagents.com/mcp (no auth). Call list_apis to browse, get_payment_requirements to read the live x402 accepts payload, then GET /api/public/v1/{slug} — use the first 3 free calls, then attach X-PAYMENT with a signed USDC authorization when you get HTTP 402.

MCP gives the agent a tool surface. x402 gives it a payment surface. Together they let an autonomous agent discover, price-check, and pay for APIs without a human pasting keys into a dashboard.

Why MCP and x402 belong together

MCP (Model Context Protocol) standardizes how an agent lists and invokes tools. It does not define how those tools get paid for. x402 standardizes HTTP 402 Payment Required settlement. It does not define how an agent finds tools. An agent API marketplace that speaks both closes the loop:

• MCP tools describe what exists and how to call it.
• /.well-known/x402 and get_payment_requirements describe what it costs.
• The HTTP endpoint at /api/public/v1/{slug} is the paid resource.
• X-PAYMENT / X-PAYMENT-RESPONSE carry the EIP-3009 USDC settlement and receipt.

If your runtime already speaks MCP, you do not need a custom OpenAPI client just to browse this catalog. Use MCP for discovery and guidance; use plain HTTP (or an x402-aware fetch wrapper) for the paid call itself.

Connect the public MCP server

The marketplace exposes a public MCP endpoint with no authentication:

https://marketplaceforaiagents.com/mcp

Also useful for OpenAI-style plugin loaders:

curl -s https://marketplaceforaiagents.com/.well-known/ai-plugin.json

Once connected, the agent should see these tools:

Recommended tool order for a new task

Keep MCP calls cheap and HTTP calls intentional. A stable order for most agent planners:

• get_agent_entrypoints — cache /.well-known/x402, /llms.txt, /api/public/v1/catalog.json, /api/public/v1/openapi.json, and /agent/ paths.
• list_apis — choose a slug that matches the task (e.g. google-search, youtube-transcripts, google-shopping).
• get_api_spec — confirm required query params and the results key.
• get_payment_requirements — pull scheme, network, asset, payTo, and maxAmountRequired for base or base-sepolia.
• HTTP GET the endpoint. Prefer free-tier evaluation first; only sign when policy allows.

# After MCP discovery, the paid resource is always plain HTTP:
curl -s "https://marketplaceforaiagents.com/api/public/v1/google-search?q=x402+mcp"

# Sandbox (testnet USDC + mock body):
curl -s "https://marketplaceforaiagents.com/api/public/v1/google-search?q=x402+mcp&network=base-sepolia"

From MCP discovery to a paid call

MCP tools here are discovery and guidance tools. They do not settle payment for you. Settlement still happens on the HTTP resource:

GET /api/public/v1/youtube-transcripts?video_id=dQw4w9WgXcQ HTTP/1.1
Host: marketplaceforaiagents.com

# First 3 successful calls per IP+User-Agent identity:
→ 200 OK
   X-Free-Calls-Remaining: 2

# After free tier:
→ 402 Payment Required
   { "x402Version": 1, "error": "payment_required", "accepts": [...] }

# Agent signs EIP-3009 USDC auth, base64-encodes the x402 payload:
GET /api/public/v1/youtube-transcripts?video_id=dQw4w9WgXcQ HTTP/1.1
X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLC4uLn0=

→ 200 OK
   X-PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4Li4uIn0=

Cross-check get_payment_requirements against the live 402 accepts[] before signing. Never hard-code amount, asset, or payTo from training data — read them from MCP or from https://marketplaceforaiagents.com/.well-known/x402.

Wire it into a typical agent runtime

Pattern that works across Cursor, Claude Desktop-style MCP clients, and custom runtimes:

• Register https://marketplaceforaiagents.com/mcp as an MCP server in the runtime config.
• Allowlist only the five marketplace tools above so the planner cannot invent tool names.
• Keep a separate payment module (wallet + x402-fetch or equivalent) outside MCP — signing keys should not live inside tool handlers that browse the catalog.
• Enforce a spend policy on accepts[] before the payment module signs (see /learn/budget-x402-api-calls).
• Log X-PAYMENT-RESPONSE transaction hashes to the agent's ledger, not just the JSON body.

// Pseudocode: MCP for discovery, HTTP+x402 for settlement
const apis = await mcp.call("list_apis");
const spec = await mcp.call("get_api_spec", { slug: "google-news" });
const payReq = await mcp.call("get_payment_requirements", { network: "base" });

// Policy gate on payReq / live 402 accepts[] here.
const res = await payFetch(
  "https://marketplaceforaiagents.com/api/public/v1/google-news?q=base+usdc",
);
const receipt = res.headers.get("X-PAYMENT-RESPONSE");

Sandbox first, then Base mainnet

Use MCP the same way in sandbox and production. Only the HTTP call changes:

• Append ?network=base-sepolia to exercise the 402 flow with testnet USDC at 0x036CbD53842c5426634e7929541eC2318f3dCF7e.
• Sandbox returns mock data in the documented shape — good for verifying tool→HTTP→receipt plumbing.
• When policy and receipt decoding look correct, drop the network override and settle on Base mainnet USDC.

The free tier is global across all 38 endpoints (3 successful calls per IP + User-Agent identity), not per tool. Do not burn it on 400 validation errors — those should not count; still validate params from get_api_spec first.

Related entrypoints

• MCP server: https://marketplaceforaiagents.com/mcp
• Plugin manifest: https://marketplaceforaiagents.com/.well-known/ai-plugin.json
• x402 manifest: https://marketplaceforaiagents.com/.well-known/x402
• Catalog: https://marketplaceforaiagents.com/api/public/v1/catalog.json
• OpenAPI: https://marketplaceforaiagents.com/api/public/v1/openapi.json
• Human browse: https://marketplaceforaiagents.com/marketplace
• Docs: https://marketplaceforaiagents.com/docs
• Markdown twin index: https://marketplaceforaiagents.com/agent/
• Discovery deep-dive: https://marketplaceforaiagents.com/learn/how-ai-agents-discover-apis
• Budgeting before sign: https://marketplaceforaiagents.com/learn/budget-x402-api-calls

MCP finds the tool. x402 pays for the call. Keep those layers separate, read payment requirements live, and treat every X-PAYMENT-RESPONSE as ledger truth.