@bolthub/mcp-bridge

MCP (Model Context Protocol) server that bridges AI agents to bolthub L402 paywalled APIs. It auto-discovers endpoints from a gateway's OpenAPI spec and handles Lightning payments transparently.

Install

npm install -g @bolthub/mcp-bridge

Or use directly with npx:

npx @bolthub/mcp-bridge --gateway https://pokemon.gw.bolthub.ai

Configuration

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

{
  "mcpServers": {
    "pokemon-api": {
      "command": "npx",
      "args": ["@bolthub/mcp-bridge", "--gateway", "https://pokemon.gw.bolthub.ai"],
      "env": {
        "NWC_URI": "<your-nwc-connection-string>"
      }
    }
  }
}

Environment Variables

The bridge supports multiple wallet types. You only need one.

| Variable | Description | |----------|-------------| | PHOENIXD_URL | Recommended. Phoenixd HTTP API URL (e.g. https://phoenixd-xxxx.nodana.app). Fast (<200ms), self-custodial with automatic channel/liquidity management. | | PHOENIXD_PASSWORD | HTTP password for Phoenixd. Required when using PHOENIXD_URL. | | LND_REST_HOST | LND REST API URL (e.g. https://your-node:8080). Fastest payment speed (<200ms). Advanced option that requires self-hosting (or Umbrel) with self-managed channels. | | LND_MACAROON | Hex-encoded admin macaroon for LND. Required when using 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 when using 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. |

Priority order: If multiple wallet types are configured, the bridge uses the first available: LND > LNbits > Phoenixd > NWC.

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, or use --budget:

npx @bolthub/mcp-bridge --gateway https://pokemon.gw.bolthub.ai --budget 1000

Guidance: 100–500 for testing, 1000–5000 for daily dev, 10000+ for production. Unset = no limit.

Alternatives

This bridge is one way to give agents L402 payment capabilities. There are also third-party MCPs that handle Lightning payments:

• Alby MCP -- Recommended for most users. Uses NWC under the hood. Works with any Alby Hub or CoinOS wallet.
• Fewsats MCP -- Zero-config custodial option. Single API key, no Lightning node needed.

For more options, see the Start Earning guide.

How it works

1. On startup, fetches the gateway's OpenAPI spec from /.well-known/openapi.json
2. Converts each API endpoint into an MCP tool with proper inputSchema
3. When an agent calls a tool, makes the HTTP request to the gateway
4. If the gateway returns 402 (Payment Required), automatically pays the Lightning invoice and retries
5. Returns the API response to the agent

SDKs

For building custom agents without MCP, use our SDKs directly:

• TypeScript: npm install @bolthub/agent
• Python: pip install bolthub

License

MIT