MCP Server

Overview

@bolthub/mcp is the bolthub MCP server. One entry in your MCP client config; behind it, three kinds of tool source sharing one wallet and one Lightning budget:

• The bolthub marketplace: search, inspect, and call every listed API through six meta-tools (search_apis, get_api_details, preview_cost, call_api, plus the Node Launcher tools). New listings appear automatically, with no config changes.
• Specific L402 gateways: a gateway's OpenAPI endpoints become directly-named tools.
• Your other MCP servers: local or remote, proxied transparently. Free tools pass straight through; a tool that answers with an L402 payment challenge is paid inside your budget and retried.

It replaces @bolthub/mcp-registry and @bolthub/mcp-bridge (both deprecated; see migration).

Quick start (zero config)

Use directly with npx (no install required). Add to your MCP client config (Cursor, Claude Desktop, Claude Code, etc.):

{
  "mcpServers": {
    "bolthub": {
      "command": "npx",
      "args": ["-y", "@bolthub/mcp"],
      "env": {
        "LND_REST_HOST": "https://your-lnd-node:8080",
        "LND_MACAROON": "<hex-admin-or-pay-macaroon>"
      }
    }
  }
}

With no config file this runs in marketplace mode: every API on bolthub.ai is available to your agent through the meta-tools.

To expose one specific gateway's endpoints as named tools instead, pass --gateway:

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

No install-time dependencies to manage. Everything ships in one bundle, including NWC wallet support and the @bolthub/pay payment core.

The server is listed in the official MCP registry as ai.bolthub/mcp — the namespace is cryptographically verified against the bolthub.ai domain, so MCP clients that support registry discovery can find and install it by that name.

Client-specific setup

Cursor: Open Settings > Features > MCP Servers > Add new MCP server. Or paste the JSON config into .cursor/mcp.json in your project root.

Claude Desktop: Open Settings > Developer > Edit Config. Paste into the mcpServers section.

Claude Code: Run claude mcp add bolthub -- npx -y @bolthub/mcp and export your wallet env vars in your shell.

The config file

For anything beyond one source, use ~/.bolthub/mcp.json (picked up automatically when present, or pass --config <path>). The mcpServers block is the exact shape your MCP client already uses, so paste your existing entries in wholesale; remote entries take {url, headers}:

{
  "marketplace": true,
  "gateways": ["https://btc-intel.gw.bolthub.ai"],
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/notes"]
    },
    "remote-tools": {
      "url": "https://tools.example.com/mcp",
      "headers": { "Authorization": "Bearer …" }
    }
  },
  "budget":     { "sat": 10000 },   // lifetime ceiling for this run, ALL sources combined
  "maxPerCall": { "sat": 500 },     // per-call ceiling
  "namespace":  "prefix",           // "prefix" (default) or "flat"
  "telemetry":  false               // reserved; v1 sends nothing anywhere
}

Then point the client at it:

{
  "mcpServers": {
    "bolthub": {
      "command": "npx",
      "args": ["-y", "@bolthub/mcp", "--config", "~/.bolthub/mcp.json"],
      "env": { "PHOENIXD_URL": "…", "PHOENIXD_PASSWORD": "…" }
    }
  }
}

mcpServers keys may not contain __ (reserved as the namespace separator).

Flags

bolthub-mcp [flags]                      zero config = marketplace mode
bolthub-mcp --gateway <url>              a specific gateway's endpoints as tools
bolthub-mcp --config ~/.bolthub/mcp.json full config (marketplace + gateways + mcpServers)

What the agent sees

• Marketplace meta-tools, unprefixed: search_apis, get_api_details, preview_cost, call_api, deploy_node, node_status.
• Gateway endpoints, prefixed by gateway slug: btc-intel__get_v1_history_candles, ….
• Downstream MCP tools, prefixed by their config key: filesystem__read_file, ….

Two servers can both expose a search tool; prefixing keeps them apart. namespace: "flat" passes bare names through instead and fails at startup on any collision (a tool is never silently shadowed).

Marketplace meta-tools

The marketplace source exposes six tools to your AI agent: four for using marketplace APIs and two for deploying your own Lightning node via the bolthub Node Launcher.

search_apis

Search the 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: "btc-intel" })

preview_cost

Preview the cost of calling an API endpoint without making the request or paying. Use this to check pricing before committing.

preview_cost({ slug: "btc-intel", path: "/v1/history/candles" })

call_api

Call any API endpoint. Lightning payments are handled automatically.

call_api({ slug: "btc-intel", path: "/v1/history/candles", method: "GET" })
call_api({ slug: "my-api", path: "/analyze", method: "POST", body: { text: "hello" }, max_cost_sats: 50 })

The optional max_cost_sats parameter is enforced against the invoice amount: invoices above it are refused, not paid.

After each call, the response includes spending information: how many sats were spent and how much budget remains.

deploy_node

Deploy a new non-custodial Lightning node on a VPS via the bolthub Node Launcher. Useful when the agent needs its own receiving wallet but doesn't have one yet.

deploy_node({ provider: "hetzner", api_key: "<vps-api-key>" })
deploy_node({ provider: "scaleway", api_key: "<vps-api-key>", region: "fr-par", tor: true })

Supported provider values: hetzner, digitalocean, lunanode, vultr, scaleway. Returns a node_id that you can pass to node_status. The user must complete wallet setup (writing down their seed phrase) on the deployed node's Lightning Terminal UI before the node can receive payments.

node_status

Check the status of a node deployed via deploy_node. Returns the current state (provisioning → installing → wallet_pending → syncing → ready), IP address, sync progress, and setup instructions when applicable.

node_status({ node_id: "<node-id-from-deploy_node>" })

Wallets

The server needs a Lightning wallet to pay for tool calls. You only need one wallet type, set in the server's env.

No wallet is not an error: free tools and marketplace search keep working; paid calls return their payment challenge with a setup hint.

Priority order: if multiple wallet types are configured, the first available wins: LND > LNbits > Phoenixd > NWC.

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 (the client retries 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 — 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. Phoenixd is the equally fast self-custodial alternative if you already run it.
• Whatever the wallet: always set a budget on connections an agent can spend from.

Budget: one pool, hard guarantee

budget.sat caps what the server can spend over its lifetime — across gateway calls, call_api, and paid downstream MCP tools combined. Reservations are synchronous, so concurrent calls on different sources can't jointly overspend. The agent can never lift the ceiling; refusals come back as clean "Payment refused" results instead of payments.

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

• budget.sat: 0 is valid and means "free tools only".
• Unset means no limit (the server warns at startup; pays any invoice as long as the wallet has funds).
• maxPerCall.sat (or --max-per-call) caps each individual payment; max_cost_sats on call_api tightens it further for one call.
• The budget lasts as long as the server process runs, typically the lifetime of your Cursor or Claude Desktop window.

Every payment logs one line to stderr (your local audit trail). The telemetry flag is reserved: v1 sends nothing anywhere, on or off; if a future version adds an opt-in ingest it will carry { scheme, asset, amount } only — no tool arguments, no resource identity.

Migrating from mcp-registry / mcp-bridge

The wallet env vars are unchanged. The old packages are deprecated on npm but not unpublished; existing configs keep working until you switch.

Remove the old entries from your client config rather than stacking them next to this one — a nested bolthub bin inside mcpServers would pay from its own wallet env, invisible to the shared budget (the server warns at startup if it spots this).

Notes & limits (v1)

• Proxies MCP tools only — no resources, prompts, or sampling passthrough yet.
• The downstream tool list is snapshotted at startup; hot add/remove needs a restart.
• A downstream that fails to start is skipped with a stderr warning; the rest keep serving. If every source fails, the server exits.
• Everything logs to stderr, never stdout (stdout is the MCP channel).

Alternatives

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

• Alby MCP: 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 building custom agents without MCP, use @bolthub/pay (TypeScript) or bolthub (Python) directly.

Registry listing

@bolthub/mcp is published in the official MCP registry as ai.bolthub/mcp. The ai.bolthub/* namespace is verified via a DNS proof on the bolthub.ai apex, and each listing version maps to the matching @bolthub/mcp release on npm (which itself carries the mcpName field the registry validates against).