@bolthub/mcp-bridge

@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.

Source: signaltech-org/bolthub-sdk · Docs: docs.bolthub.ai

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
LND_REST_HOST	Recommended. LND REST API URL (e.g. from the bolthub Node Launcher or https://your-node:8080). Fast (<200ms), self-hosted, full control. Use a pay-scoped macaroon in production.
LND_MACAROON	Hex-encoded macaroon for LND. Required when using LND_REST_HOST.
NWC_URI	Recommended for easy setup. Works with any NWC-compatible wallet: CoinOS (free), Alby Hub, Zeus, Primal, and more. Slower (1-3s) but no node required.
LNBITS_URL	LNbits instance URL. Fast (<300ms). Accounts system built on any Lightning funding source. Use if you already run LNbits.
LNBITS_ADMIN_KEY	Admin API key for LNbits. Required when using LNBITS_URL.
PHOENIXD_URL	Phoenixd HTTP API URL. Supported if you already run Phoenixd for outbound payments.
PHOENIXD_PASSWORD	HTTP password for Phoenixd. Required when using PHOENIXD_URL.
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 > NWC > LNbits > Phoenixd.

Which wallet should I use?

• Default for production / self-hosted nodes: LND via the bolthub Node Launcher, or your own LND (self-hosted or via Umbrel) with a pay-scoped macaroon. Fastest and most reliable.
• Just getting started without a node? Use NWC with any compatible wallet like CoinOS (free) or Alby Hub. Easiest to set up but slower (1-3s).

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

• On startup, fetches the gateway's OpenAPI spec from /.well-known/openapi.json
• Converts each API endpoint into an MCP tool with proper inputSchema
• When an agent calls a tool, makes the HTTP request to the gateway
• If the gateway returns 402 (Payment Required), automatically pays the Lightning invoice and retries
• 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

Security & trust

This package handles your Lightning wallet credentials, so here is exactly what it does with them:

• Your credentials never reach bolthub. Wallet secrets (LND_MACAROON, NWC_URI, LNBITS_ADMIN_KEY, PHOENIXD_PASSWORD) are read from env vars and passed only to the matching wallet adapter, which talks to the wallet you configured. They are never sent to bolthub servers, never persisted, and never logged.
• Endpoints contacted: the gateway you pass via --gateway and your configured wallet. Nothing else — no telemetry or analytics.
• Local state: paid L402 session tokens (not credentials) are cached in ~/.bolthub/sessions.json with 0600 permissions, so an already-paid session is reused instead of paying again.
• Spend control: BUDGET_SATS caps spending per server process (restarting your MCP client starts a fresh session and resets the cap). Use a pay-scoped macaroon or a small dedicated wallet for defense in depth.
• Auditable source & provenance: the full source lives at signaltech-org/bolthub-sdk (packages/mcp-bridge). The published dist/index.js is bundled from it with Bun, has zero runtime npm dependencies, and ships a source map with embedded sources. Releases are published from that repo's CI with npm provenance — verify with npm audit signatures.

License

MIT