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://pokemon.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": {
    "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 payments for agents; use a pay-scoped macaroon in production.
`LND_MACAROON`	Hex-encoded 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`.
`PHOENIXD_URL`	Phoenixd HTTP API URL. Use if you already run Phoenixd for programmatic outbound payments. Fast (<200ms).
`PHOENIXD_PASSWORD`	HTTP password for Phoenixd. Required when using `PHOENIXD_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 return an error instead of paying. 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?

Default for new setups: LND via the bolthub Node Launcher, or your own LND with REST (see Umbrel or similar if you self-host). Best fit when you want speed and control for agent payments.
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).
Already on Phoenixd? Keep using PHOENIXD_URL + PHOENIXD_PASSWORD for paying; it stays supported.

Spending budget

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

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

Budget	Use case
`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 wallet has funds)

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

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

TypeScript: @bolthub/agent
Python: bolthub

MCP Bridge