Overview

The MCP Registry gives AI agents access to every API on the bolthub marketplace through a single config entry. New APIs are instantly available, with no config changes needed.

This is the recommended way to connect AI agents to bolthub.

Install

Use directly with npx (no install required):

npx @bolthub/mcp-registry

Or install globally:

npm install -g @bolthub/mcp-registry

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, Claude Code, etc.):

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

Every API on bolthub.ai is now available to your agent.

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 @bolthub/mcp-registry and export your wallet env vars in your shell.

Environment variables

The registry needs a Lightning wallet to pay for API calls. You only need one wallet type.

Variable	Description
`LND_REST_HOST`	Recommended. LND REST API URL (bolthub Node Launcher or your own node). Fast payment path for agents. Use a pay-scoped macaroon in production (see Agent wallet security).
`LND_MACAROON`	Hex-encoded macaroon for LND. Required with `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 with `LNBITS_URL`.
`NWC_URI`	Easiest setup. Works with any NWC-compatible wallet: CoinOS (free), Alby Hub, Phoenix, Zeus, and more. Slower (1-3s).
`PHOENIXD_URL`	Phoenixd HTTP API URL. Supported for agents that already run Phoenixd for outbound payments. Fast (<200ms).
`PHOENIXD_PASSWORD`	HTTP password for Phoenixd. Required with `PHOENIXD_URL`.
`BUDGET_SATS`	Optional. Maximum sats the MCP can spend per session. When exceeded, API calls are refused. Unset = unlimited.

Which wallet should I use?

Default for new setups: LND via the bolthub Node Launcher, or your own LND with REST and a scoped macaroon. Fast and a good fit for production agents.
Just getting started without a node? Use NWC with CoinOS (free) or Alby Hub. Easiest to set up but slower (1-3s).
Already on Phoenixd? Keep using PHOENIXD_URL + PHOENIXD_PASSWORD for paying; no need to migrate unless you want to.

Spending budget

Set BUDGET_SATS to cap total spending per session (the session lasts as long as the MCP server process runs, typically the lifetime of your Cursor or Claude Desktop window).

"env": { "LND_REST_HOST": "...", "LND_MACAROON": "...", "BUDGET_SATS": "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 the wallet has funds)

Tools

The registry exposes four tools to your AI agent:

`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: "pokemon" })

`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: "pokemon", path: "/v2/pokemon/pikachu" })

`call_api`

Call any API endpoint. Lightning payments are handled automatically.

call_api({ slug: "pokemon", path: "/v2/pokemon/pikachu", method: "GET" })
call_api({ slug: "my-api", path: "/analyze", method: "POST", body: { text: "hello" }, max_cost_sats: 50 })

The optional max_cost_sats parameter rejects invoices above the specified amount.

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

How it works

search_apis queries the live bolthub directory, and new APIs appear immediately
get_api_details fetches endpoint specs so the agent knows how to call them
preview_cost checks pricing without paying
call_api hits the gateway, pays any L402 invoice automatically, and returns the response

vs MCP Bridge

	Registry (`mcp-registry`)	Bridge (`mcp-bridge`)
Config	One entry, every API	One entry per API
New APIs	Instant	Requires config change
Tool count	4 (fixed)	N (one per endpoint)
Best for	General-purpose agents	Dedicated single-API agents

Use the registry for most cases. Use the MCP Bridge when you want direct, named tools for a specific API.

Getting listed in popular MCP registries

If you want @bolthub/mcp-registry (or any MCP server) discoverable in public registries, use this process:

Publish a stable package first (npm/PyPI/Docker) with a clear install command (npx ..., uvx ..., or container run command).
Ship complete metadata in your repo and package docs:
- What the server does (one-line value prop)
- Transport (stdio and/or http)
- Required env vars (and which are optional)
- Authentication model
- Tool list with short descriptions and examples
Keep startup friction near zero:
- Works with one command
- Fast startup (<2-3s on cold start)
- Clear error messages for missing env vars
Add trust signals:
- OSS license
- README with quickstart + troubleshooting
- Automated tests and CI
- Versioned releases/changelog
Submit to target registries and follow each registry's contribution rules exactly.

GitHub MCP Registry

GitHub maintains a public MCP Registry where servers can be submitted and discovered: MCP Registry on GitHub.

Typical acceptance blockers are incomplete docs, unclear auth requirements, and install commands that fail on a clean machine. Before submission, test your setup from scratch on macOS and Linux with only the published instructions.

Practical checklist before you submit

Verify npx @bolthub/mcp-registry runs without local repo files
Document all wallet env var combinations users can choose from
Ensure tool names/descriptions are stable and backwards-compatible
Add an explicit security section (secrets handling, network access, spending limits)
Include at least one end-to-end example config for Cursor/Claude clients
Keep release notes current so registry reviewers can evaluate maintenance health

Registry submission package (copy/paste)

Use this as your baseline package when submitting @bolthub/mcp-registry to registries.

1) Short listing blurb

`@bolthub/mcp-registry` is an MCP server that gives AI agents access to every API on the bolthub marketplace through one MCP config entry.

It exposes four stable tools:
- `search_apis`: discover APIs by query/tag
- `get_api_details`: fetch endpoint and pricing metadata
- `preview_cost`: estimate sats before calling
- `call_api`: execute API requests with automatic L402 payment

Install:
`npx @bolthub/mcp-registry`

2) Compatibility + setup block

## Compatibility
- Transport: `stdio`
- Clients tested: Cursor, Claude Desktop, Claude Code
- Runtime: Node.js LTS with `npx`

## Required configuration
Set one wallet integration:
- LND: `LND_REST_HOST`, `LND_MACAROON` (recommended)
- LNbits: `LNBITS_URL`, `LNBITS_ADMIN_KEY`
- NWC: `NWC_URI`
- Phoenixd: `PHOENIXD_URL`, `PHOENIXD_PASSWORD` (if you already use it for paying)

Optional:
- `BUDGET_SATS` to cap per-session spending

3) Security disclosure block

## Security model
- The server can make outbound HTTP calls to APIs selected by the user/agent.
- Payment is explicit and auditable through Lightning invoice settlement.
- `BUDGET_SATS` provides a hard cap to prevent overspend.
- Secrets are read from environment variables; never hardcode credentials.
- Tool schema is intentionally small and stable to reduce prompt-surface risk.

4) Reproducible smoke test

# Clean environment
node -v
npx @bolthub/mcp-registry --help || true

# With wallet env configured, validate startup
LND_REST_HOST=... LND_MACAROON=... npx @bolthub/mcp-registry

5) Registry PR template

## MCP server submission: @bolthub/mcp-registry

### What it does
Provides a single MCP server entry that exposes every API listed on bolthub.ai.

### Install
`npx @bolthub/mcp-registry`

### Transport
`stdio`

### Authentication / secrets
Uses wallet credentials via environment variables (LND, LNbits, NWC, or Phoenixd). Supports optional spend cap with `BUDGET_SATS`.

### Tools
- `search_apis`
- `get_api_details`
- `preview_cost`
- `call_api`

### Quick validation performed
- [ ] Starts on a clean machine with the documented command
- [ ] Env var requirements documented and verified
- [ ] README includes examples for Cursor/Claude setup
- [ ] Security considerations documented
- [ ] License and CI checks present

Registry-specific variants

A) GitHub MCP Registry variant

Use this when opening a PR to the GitHub MCP Registry: MCP Registry on GitHub.

## Server name
bolthub

## Package
@bolthub/mcp-registry

## Install command
npx @bolthub/mcp-registry

## Category
Developer tools / API marketplace

## Description
One MCP config entry that gives AI agents discover + call access to every API on the bolthub marketplace.

## Transport
stdio

## Auth and secrets
Configured via env vars for one wallet type:
- LND_REST_HOST + LND_MACAROON
- LNBITS_URL + LNBITS_ADMIN_KEY
- NWC_URI
- PHOENIXD_URL + PHOENIXD_PASSWORD

Optional:
- BUDGET_SATS (session spending cap)

## Exposed tools
- search_apis
- get_api_details
- preview_cost
- call_api

## Verification notes
- Validated startup from clean environment
- README includes Cursor/Claude setup
- Security section documents secrets handling and spend limits

B) JSON metadata variant (generic registries)

Some directories ask for a machine-readable metadata object. Use this as a starter:

{
  "name": "bolthub",
  "display_name": "bolthub MCP Registry",
  "package": {
    "manager": "npm",
    "name": "@bolthub/mcp-registry",
    "install": "npx @bolthub/mcp-registry"
  },
  "description": "One MCP config entry to discover and call every API on the bolthub marketplace.",
  "transport": ["stdio"],
  "documentation_url": "https://bolthub.ai/docs/sdks/mcp-registry",
  "repository_url": "https://github.com/bolthub-ai/bolthub.ai",
  "license": "MIT",
  "tools": [
    {
      "name": "search_apis",
      "description": "Search marketplace APIs by query or tag."
    },
    {
      "name": "get_api_details",
      "description": "Get endpoint specs, examples, and pricing metadata."
    },
    {
      "name": "preview_cost",
      "description": "Estimate sats cost before making a paid request."
    },
    {
      "name": "call_api",
      "description": "Call an endpoint with automatic L402 Lightning payment."
    }
  ],
  "env": {
    "one_of": [
      ["LND_REST_HOST", "LND_MACAROON"],
      ["LNBITS_URL", "LNBITS_ADMIN_KEY"],
      ["NWC_URI"],
      ["PHOENIXD_URL", "PHOENIXD_PASSWORD"]
    ],
    "optional": ["BUDGET_SATS"]
  },
  "security": {
    "secrets_source": "environment variables",
    "network_access": "outbound HTTP requests to selected APIs",
    "cost_controls": ["BUDGET_SATS"]
  },
  "compatibility": {
    "clients_tested": ["Cursor", "Claude Desktop", "Claude Code"]
  }
}

Final filled submission draft (ready to paste)

GitHub MCP Registry PR (filled)

## MCP server submission: bolthub

### Package
`@bolthub/mcp-registry`

### Repository
`https://github.com/signaltech-org/bolthub.ai` (directory: `packages/mcp-registry`)

### Documentation
`https://docs.bolthub.ai/docs/sdks/mcp-registry`

### Install
`npx @bolthub/mcp-registry`

### Description
`@bolthub/mcp-registry` is an MCP server that gives AI agents discover + call access to every API on the bolthub marketplace via one MCP config entry.

### Transport
`stdio`

### Authentication / secrets
One wallet integration is required (via env vars):
- `LND_REST_HOST` + `LND_MACAROON`
- `LNBITS_URL` + `LNBITS_ADMIN_KEY`
- `NWC_URI`
- `PHOENIXD_URL` + `PHOENIXD_PASSWORD`

Optional:
- `BUDGET_SATS` (hard spend cap per MCP server session)

### Exposed tools
- `search_apis` (discover APIs by query/tag)
- `get_api_details` (fetch endpoint/pricing metadata)
- `preview_cost` (estimate sats cost before execution)
- `call_api` (execute endpoint with automatic L402 payment)

### License
`MIT`

### Validation checklist
- [x] Install command works on clean machine: `npx @bolthub/mcp-registry`
- [x] Env var requirements documented for all wallet modes
- [x] Cursor/Claude setup examples documented
- [x] Cost control documented (`BUDGET_SATS`)
- [x] Open-source license declared

Generic registry JSON payload (filled)

{
  "name": "bolthub",
  "display_name": "bolthub MCP Registry",
  "package": {
    "manager": "npm",
    "name": "@bolthub/mcp-registry",
    "version": "0.1.0",
    "install": "npx @bolthub/mcp-registry"
  },
  "description": "MCP server that gives AI agents discover and call access to every API on the bolthub marketplace through a single config entry.",
  "transport": ["stdio"],
  "documentation_url": "https://docs.bolthub.ai/docs/sdks/mcp-registry",
  "repository_url": "https://github.com/signaltech-org/bolthub.ai",
  "repository_subdirectory": "packages/mcp-registry",
  "license": "MIT",
  "tools": [
    {
      "name": "search_apis",
      "description": "Search marketplace APIs by query or tag."
    },
    {
      "name": "get_api_details",
      "description": "Get endpoint specs, examples, and pricing metadata for a slug."
    },
    {
      "name": "preview_cost",
      "description": "Preview sats cost before making a paid endpoint request."
    },
    {
      "name": "call_api",
      "description": "Call an API endpoint with automatic L402 Lightning payment handling."
    }
  ],
  "env": {
    "one_of": [
      ["LND_REST_HOST", "LND_MACAROON"],
      ["LNBITS_URL", "LNBITS_ADMIN_KEY"],
      ["NWC_URI"],
      ["PHOENIXD_URL", "PHOENIXD_PASSWORD"]
    ],
    "optional": ["BUDGET_SATS"]
  },
  "security": {
    "secrets_source": "environment variables",
    "network_access": "outbound HTTP requests to selected marketplace APIs",
    "cost_controls": ["BUDGET_SATS"]
  },
  "compatibility": {
    "clients_tested": ["Cursor", "Claude Desktop", "Claude Code"]
  }
}

MCP Registry

On this page