MCP Bridge

Overview

@bolthub/mcp-bridge is an 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://btc-intel.gw.bolthub.ai

Minimal dependencies. Only @modelcontextprotocol/sdk and zod beyond the core @bolthub/agent (which itself has zero runtime dependencies).

Configuration

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

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

Environment variables

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

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

Which wallet should I use?

Pick by how your wallet will be used, not by brand:

• Interactive use (you're present): Zeus — free, non-custodial, well-known. Great for trying APIs from the playground or manual CLI calls. Not for unattended agents: its wallet service runs on your phone, so payments only succeed while the app is running.
• Unattended agents, free start: NWC with CoinOS — the only zero-cost always-on option; about 2 minutes to a working wallet. Set a per-connection budget and keep only a few thousand sats there (it's custodial). Its relay refuses connections intermittently; retry the call if it fails to connect (clients built on @bolthub/agent ≥ 0.1.3 retry automatically).
• Unattended agents, reliable: Alby Hub (v1.21.5+) — non-custodial, two relays in every connection string with automatic failover in our client. Hosted plan or free self-hosted.
• Production / power users: LND via the bolthub Node Launcher or your own node with a pay-scoped macaroon (see Umbrel or similar if you self-host) — payments in under 200ms. Pairs naturally with Lightning Labs' agent stack (lnget, lightning-agent-tools), which speaks the same standard L402 as every bolthub API.
• Whatever the wallet: always set a budget on connections an agent can spend from.

Spending budget

Set BUDGET_SATS to cap spending per session, or use the --budget CLI flag:

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

A session lasts as long as the MCP server process runs, typically the lifetime of your Cursor or Claude Desktop window.

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.

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 the SDKs directly:

• TypeScript: @bolthub/agent
• Python: bolthub