Keyless MCP and the 402 payment loop for agents

Agents can't fill in sign-up forms, and they shouldn't have to. Our goal was simple to state: an agent that lands on our domain can discover the API, call it with no account, and surface a payment link to its human when the free tier runs out, all from machine-readable files and responses.

1. Discovery

• /llms.txt: what the API is, the price, keyless access, one curl example, the 402 loop and the MCP install line.
• /.well-known/mcp.json: the MCP package, its 6 tools with their input schemas, and auth marked optional.
• /robots.txt: alongside the usual rules, comment-safe hints such as the API URL and “trial key: none needed”.

2. Keyless by default

Send no Authorization header, or send Bearer keyless or Bearer guest, and you are on the free tier: 25 requests per IP per UTC day, counted per /64 for IPv6 so rotating addresses doesn't multiply it. Failed keyless requests still count. Every billable response carries X-Credits-Remaining, so the agent always knows where it stands.

The MCP server works the same way. One line, no key:

claude mcp add contextfetch -- npx -y @contextfetch/mcp

3. The 402

When the allowance or a key's credits run out, the API answers HTTP 402 with an X-Payment-URL header and a body an agent can act on without guessing:

{
  "error": "keyless_limit",
  "message": "Daily free tier limit (25 requests) reached. Reload 15,000 searches for $15.",
  "checkout_url": "https://contextfetch.dev/#buy",
  "pricing": {
    "pack_size": 15000,
    "price_usd": 15,
    "unit_cost_usd": 0.001
  },
  "packs": [
    {
      "id": "instant",
      "name": "Instant",
      "credits": 15000,
      "price_usd": 15,
      "cost_per_1k": 1,
      "recommended": false,
      "checkout_url": "https://api.contextfetch.dev/buy/instant"
    },
    {
      "id": "builder",
      "name": "Builder",
      "credits": 60000,
      "price_usd": 50,
      "cost_per_1k": 0.83,
      "recommended": true,
      "checkout_url": "https://api.contextfetch.dev/buy/builder"
    },
    {
      "id": "scale",
      "name": "Scale",
      "credits": 200000,
      "price_usd": 150,
      "cost_per_1k": 0.75,
      "recommended": false,
      "checkout_url": "https://api.contextfetch.dev/buy/scale"
    }
  ],
  "action": {
    "type": "payment_link",
    "url": "https://api.contextfetch.dev/buy/instant",
    "prompt_to_user": "ContextFetch credits ran out. Reload 15,000 searches for $15: https://api.contextfetch.dev/buy/instant"
  }
}

action.prompt_to_user is a sentence the agent can show as is. packs lists every option, with recommended on one. The MCP tools return the same link as an error result instead of crashing, so the conversation keeps going.

4. One click to pay

Every link in that body is our own /buy/<pack> URL, never a raw Stripe link, so pricing changes in one place. It answers 303 straight to Stripe Checkout: no pricing page, no confirm step. After payment, the success page at contextfetch.dev/success shows the key and copies it to the clipboard. We store only its SHA-256 hash.

Packs are one-time payments and credits never expire: Instant $15 for 15,000, Builder $50 for 60,000, Scale $150 for 200,000.

5. Agents that run all night

A paused agent is worse than a slightly higher bill, but a runaway bill is worse than both. Auto-reload is off by default. When the buyer turns it on, a deduction that leaves the balance below the threshold buys one pack with the saved card, as long as this month's reload spend stays within the cap. Credits are added only when the payment succeeds, and a declined card turns auto-reload off and says why.

The agent can read and change all of this through GET /v1/balance, POST /v1/billing/auto-reload or the MCP tools contextfetch_balance and contextfetch_auto_reload, with one safety rule: through the API it can turn auto-reload off, lower values or change the pack, but it can never raise the monthly cap above $500. Going higher takes a human in a browser.

The full contract is in the 402 docs, and you can watch X-Credits-Remaining count down in the playground.