@bolthub/mcp-registry

MCP server that gives AI agents access to every API on the bolthub marketplace. One config entry, every API, forever. New APIs are instantly available, with no config changes needed.

Install

npm install -g @bolthub/mcp-registry

Or use directly with npx:

npx @bolthub/mcp-registry

Configuration

Add to your MCP client config (Cursor, Claude Desktop, OpenClaw, etc.):

{
  "mcpServers": {
    "bolthub": {
      "command": "npx",
      "args": ["@bolthub/mcp-registry"],
      "env": {
        "PHOENIXD_URL": "<your-phoenixd-url>",
        "PHOENIXD_PASSWORD": "<your-phoenixd-password>"
      }
    }
  }
}

That's it. Every API on bolthub.ai is now available to your agent.

Environment Variables

The registry needs a Lightning wallet to pay for API calls. You only need one wallet type.

| Variable | Description | |----------|-------------| | PHOENIXD_URL | Recommended. Phoenixd HTTP API URL. Fast (<200ms), self-custodial with automatic channel/liquidity management. Easy setup via Nodana, or self-host. | | PHOENIXD_PASSWORD | HTTP password for Phoenixd. Required with PHOENIXD_URL. | | LND_REST_HOST | LND REST API URL. Fastest payment speed (<200ms). Advanced option that requires self-hosting (or Umbrel) with self-managed channels and liquidity. | | LND_MACAROON | Hex-encoded admin macaroon for LND. Required with LND_REST_HOST. | | LNBITS_URL | LNbits instance URL. Fast (<300ms). Open-source accounts system built on any Lightning funding source. | | LNBITS_ADMIN_KEY | Admin API key for LNbits. Required with LNBITS_URL. | | NWC_URI | Easiest setup. Works with any NWC-compatible wallet: CoinOS (free), Alby Hub, Phoenix, Zeus, and more. Slower (1-3s) and can be unreliable. | | BUDGET_SATS | Optional. Maximum sats the MCP can spend per session. When exceeded, API calls are refused. Unset = unlimited. |

Which wallet should I use?

• Just getting started? Use NWC with any compatible wallet like CoinOS (free) or Alby Hub. Easiest to set up but slower (1-3s).
• Need speed & reliability? Use Phoenixd via Nodana, fast (<200ms) and self-custodial with automatic channel management. Or self-host it for full control.
• Running in production? LND (self-hosted or via Umbrel) or Phoenixd give you the best reliability and speed. LND requires managing your own channels and liquidity.

Spending budget

Set BUDGET_SATS to cap total spending per session (the session lasts as long as the MCP server process runs, typically the lifetime of your Cursor or Claude Desktop window). You can also use the --budget CLI flag:

npx @bolthub/mcp-registry --budget 1000

Or via env var in your MCP config:

"env": { "PHOENIXD_URL": "...", "PHOENIXD_PASSWORD": "...", "BUDGET_SATS": "1000" }

Guidance:

• 100-500 - Testing and light use
• 1000-5000 - Typical daily development
• 10000+ - Heavy or production use
• Unset - No limit (pays any invoice as long as the wallet has funds)

The budget is a safety net against runaway spending. When the limit is reached, call_api returns an error instead of paying.

Tools

The registry exposes four tools to your AI agent:

search_apis

Search the bolthub marketplace for APIs by keyword or tag.

search_apis({ query: "weather" })
search_apis({ tag: "finance" })
search_apis()  // list all available APIs

get_api_details

Get full details for a specific API: endpoints, pricing, examples.

get_api_details({ slug: "pokemon" })

preview_cost

Preview the cost of calling an API endpoint without making the request or paying.

preview_cost({ slug: "pokemon" })
preview_cost({ slug: "pokemon", path: "/v2/pokemon/pikachu" })

call_api

Call any API endpoint. Lightning payments are handled automatically.

call_api({ slug: "pokemon", path: "/v2/pokemon/pikachu", method: "GET" })
call_api({ slug: "my-api", path: "/analyze", method: "POST", body: { text: "hello" } })

How it works

1. search_apis queries the live bolthub directory, and new APIs appear immediately
2. get_api_details fetches endpoint specs so the agent knows how to call them
3. preview_cost lets you check pricing before committing to a call
4. call_api hits the gateway, pays any L402 invoice automatically, and returns the response

vs @bolthub/mcp-bridge

| | Registry (mcp-registry) | Bridge (mcp-bridge) | |---|---|---| | Config | One entry, every API | One entry per API | | New APIs | Instant | Requires config change | | Tool count | 4 (fixed) | N (one per endpoint) | | Best for | General-purpose agents | Dedicated single-API agents |

Use the registry for most cases. Use the bridge when you want direct, named tools for a specific API.

License

MIT