Documentation

How to connect your agent to MCP tools through Obolo: one endpoint, one API key per API, pay per call from a prepaid balance, with spend caps and audit logs. Public draft, 2026.

Quickstart

Four steps from zero to your first tool call: (1) top up your prepaid wallet; (2) add one MCP connection per API you want to use; (3) mint an `obl_…` key for that connection; (4) your agent calls `tools/call` against the endpoint. Each call’s cost is deducted from the balance. onboarding, catalog.

Connecting

Each API has its own MCP endpoint. The connection is Streamable HTTP + JSON-RPC 2.0, authenticated with your `obl_…` key in the `Authorization` header. Replace `{serverId}` with the id of the server shown on its catalog page:

{
  "mcpServers": {
    "example-api": {
      "type": "streamable-http",
      "url": "https://api.obolo.dev/mcp/{serverId}",
      "headers": {
        "Authorization": "Bearer obl_live_xxxxxxxxxxxx"
      }
    }
  }
}

// JSON-RPC 2.0 over Streamable HTTP
POST https://api.obolo.dev/mcp/{serverId}
Authorization: Bearer obl_live_xxxxxxxxxxxx
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "geocode.forward",
    "arguments": { "query": "Buenos Aires" }
  }
}

Authentication & keys

Keys are per-API: one `obl_…` key grants access to a single connection, with its own tool view and its own spend cap. That contains the blast radius if a key leaks — a compromised key can’t spend on other APIs or exceed its cap — and lets you rotate each one independently. security.

Billing

The balance is prepaid and metering is per-call: every successful `tools/call` deducts that tool’s price from the org’s balance. When the key reaches its spend cap, the gateway returns a 402/429 and never overcharges. The balance can be funded with Stripe, prepaid USDC or x402: x402.

// key over its spend cap → charge refused, nothing overspent
HTTP/1.1 429 Too Many Requests

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32003, "message": "spend cap reached" }
}

Verification tiers

Every server carries a trust tier. The “crawled” tier (tier 1): indexed from a public directory, metadata only, no ownership check. The “verified” tier (tier 2): ownership proven via DNS + registry, and a declared schema that passed static analysis with a stable canonical hash (drift protection). Pick the tier your use case requires. glosario.

Publishing

Are you a publisher? You can list or claim your server, set pricing and keep your 80% with Obolo as merchant of record. The full guide covers claiming via DNS-TXT, per-call pricing, reaching the verified tier and settling via Stripe/USDC.

How to monetize an MCP server →

Reference

Compare · MCP gateway · Publisher · Operator · Catalog

Questions: hola@obolo.dev