Claude Desktop (MCP)

The BoltzPay MCP server gives Claude 7 tools for discovering, quoting, diagnosing, and paying for API data, all through natural language. It communicates via the Model Context Protocol, an open standard for AI tool use.

Quick Start

Open your Claude Desktop config file

macOS
Windows
Linux

~/Library/Application Support/Claude/claude_desktop_config.json

%APPDATA%\Claude\claude_desktop_config.json

~/.config/claude/claude_desktop_config.json

Add the BoltzPay server (Explore mode, no keys needed)

{
  "mcpServers": {
    "boltzpay": {
      "command": "npx",
      "args": ["-y", "@boltzpay/mcp"]
    }
  }
}

This gives Claude read-only tools: quote, discover, diagnose, budget, history, and wallet. No credentials required.

Restart Claude Desktop

Quit and reopen the app. Open Settings > MCP Servers to confirm BoltzPay is listed, or type /mcp in a conversation to check.

You can also run npx @boltzpay/mcp setup to launch an interactive wizard that writes the config file for you.

Enable Payments

To let Claude actually pay for API data, add your credentials:

{
  "mcpServers": {
    "boltzpay": {
      "command": "npx",
      "args": ["-y", "@boltzpay/mcp"],
      "env": {
        "COINBASE_API_KEY_ID": "your-key-id",
        "COINBASE_API_KEY_SECRET": "your-key-secret",
        "COINBASE_WALLET_SECRET": "your-wallet-secret",
        "TEMPO_PRIVATE_KEY": "0x...",
        "BOLTZPAY_DAILY_BUDGET": "5.00"
      }
    }
  }
}

Get your keys at portal.cdp.coinbase.com. The wallet is automatically provisioned on first use. No manual wallet setup needed.

On Windows, use "command": "cmd" and "args": ["/c", "npx", "-y", "@boltzpay/mcp"] instead.

Credential requirements

Not every tool needs keys. Only boltzpay_fetch requires credentials to make payments:

Tool	Coinbase keys	NWC string	Tempo/Stripe key
`boltzpay_fetch`	For x402	For L402	For MPP
`boltzpay_quote`	—	—	—
`boltzpay_discover`	—	—	—
`boltzpay_budget`	—	—	—
`boltzpay_history`	—	—	—
`boltzpay_wallet`	—	—	—
`boltzpay_diagnose`	—	—	—

Budget Control

Set spending limits via environment variables in your config. When a limit is hit, boltzpay_fetch returns a structured error and Claude informs you.

Variable	Description	Example
`BOLTZPAY_DAILY_BUDGET`	Max spend per day	`"5.00"`
`BOLTZPAY_MONTHLY_BUDGET`	Max spend per month	`"50.00"`
`BOLTZPAY_PER_TRANSACTION`	Max per single request	`"1.00"`

See Configuration for all environment variables and advanced options.

Tools

boltzpay_fetch

Fetch data from a paid API. Automatically detects the payment protocol (x402, L402, or MPP), pays the required amount, and returns the response.

Parameter	Type	Required	Description
`url`	`string`	Yes	URL of the paid API endpoint
`method`	`string`	No	HTTP method (default: `GET`)
`headers`	`Record<string, string>`	No	Additional HTTP headers
`body`	`string`	No	Request body
`chain`	`"evm"` \| `"svm"`	No	Override chain selection

Success

{
  "status": 200,
  "ok": true,
  "body": "{\"holdings\": [...]}",
  "payment": {
    "protocol": "x402",
    "amount": "$0.05"
  }
}

The payment field is only present when a payment was made. Free endpoints omit it.

Error

{
  "error": "PROTOCOL_ERROR",
  "message": "Payment was not accepted by the server (HTTP 402)",
  "hint": "Check the URL and try boltzpay_quote first"
}

boltzpay_quote

Check an endpoint’s cost without paying. Returns protocol, price, currency, and multi-chain alternatives when available.

Parameter	Type	Required	Description
`url`	`string`	Yes	URL to check for pricing

Paid endpoint

{
  "protocol": "x402",
  "amount": "$0.05",
  "currency": "USD",
  "network": "eip155:8453",
  "alternatives": [
    { "chain": "Solana", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "amount": "$0.05" }
  ]
}

Free endpoints return a plain text response: This endpoint does not require payment (free).

boltzpay_discover

Browse paid API endpoints from the BoltzPay registry with filtering by protocol, score, and category.

Parameter	Type	Required	Description
`category`	`string`	No	Filter by category
`protocol`	`string`	No	Filter by protocol (`x402`, `l402`, `mpp`)
`minScore`	`number`	No	Minimum trust score (0-100)
`query`	`string`	No	Search by name or URL

Output

[
  {
    "slug": "invy-token-holdings",
    "name": "Invy — Token Holdings",
    "url": "https://invy.bot/api",
    "protocol": "x402",
    "score": 85,
    "health": "healthy",
    "category": "crypto-data",
    "isPaid": true,
    "badge": "established"
  }
]

boltzpay_budget

View current spending limits, amount spent, and remaining balance. No parameters.

With budget configured

{
  "daily": {
    "limit": "$10.00",
    "spent": "$1.25",
    "remaining": "$8.75"
  },
  "perTransaction": {
    "limit": "$1.00"
  }
}

Returns No budget limits configured when no limits are set.

boltzpay_history

List all payments made during the current session. No parameters.

Output

[
  {
    "url": "https://invy.bot/api",
    "protocol": "x402",
    "amount": "$0.05",
    "chain": "Base",
    "network": "eip155:8453",
    "timestamp": "2026-02-19T14:30:00.000Z",
    "txHash": "0xabc123..."
  }
]

Returns No payments made yet when the session has no transactions.

boltzpay_diagnose

Run a full diagnostic on any API endpoint in under 2 seconds. Checks DNS resolution, HTTP reachability, protocol detection (x402/L402), format version, pricing, and latency. No credentials required.

Parameter	Type	Required	Description
`url`	`string`	Yes	URL of the endpoint to diagnose

Output

{
  "url": "https://invy.bot/api",
  "dns": { "ok": true, "ip": "76.76.21.21", "ms": 12 },
  "get": { "status": 402, "ms": 245 },
  "protocol": "x402",
  "version": "v1",
  "price": "$0.05",
  "network": "eip155:8453",
  "health": "paid",
  "totalMs": 257
}

The health field classifies the endpoint into one of four states:

Health	Meaning
`paid`	Online and requiring payment (x402 or L402 detected)
`free_confirmed`	Online but no payment protocol detected
`dead`	Unreachable (DNS failure, timeout, or server error)
`ambiguous`	Reachable but inconclusive protocol detection

boltzpay_wallet

View wallet addresses, balances, network, supported protocols, and budget configuration. No parameters.

Output

{
  "network": "base",
  "protocols": ["x402", "l402"],
  "chains": ["evm", "svm"],
  "addresses": {
    "evm": "0x1234...abcd",
    "svm": "7xKX...9mNq"
  },
  "balances": {
    "evm": "$12.50",
    "svm": "$5.00"
  },
  "budget": {
    "daily": { "limit": "$10.00", "spent": "$1.25", "remaining": "$8.75" }
  }
}

When credentials are not set, balances returns "Balance unavailable". Without budget config, budget returns "No limits configured".

Error Handling

All tools return structured errors with isError: true. The format is consistent:

{
  "error": "ERROR_TYPE",
  "message": "Human-readable description",
  "hint": "Suggested next step"
}

Error type	Trigger	Hint
`BUDGET_EXCEEDED`	Exceeds a configured budget limit	Use `boltzpay_budget` to check limits
`INSUFFICIENT_FUNDS`	Not enough USDC in wallet	Top up your USDC balance
`MISSING_CREDENTIALS`	Coinbase credentials not set	Set the three `COINBASE_*` env vars
`PROTOCOL_ERROR`	Payment protocol failure	Try `boltzpay_quote` first to verify
`NETWORK_ERROR`	Endpoint unreachable or timeout	Verify the endpoint is reachable
`INTERNAL_ERROR`	Unexpected server error	Check logs (`BOLTZPAY_LOG_LEVEL=debug`)

Environment Variables

Variable	Description	Default
`COINBASE_API_KEY_ID`	CDP API key ID	—
`COINBASE_API_KEY_SECRET`	CDP API key secret	—
`COINBASE_WALLET_SECRET`	CDP wallet secret	—
`NWC_CONNECTION_STRING`	Enables L402 protocol (Lightning)	—
`TEMPO_PRIVATE_KEY`	Tempo wallet private key (enables MPP)	—
`STRIPE_SECRET_KEY`	Stripe secret key (enables Stripe MPP)	—
`BOLTZPAY_DAILY_BUDGET`	Daily spending cap in USD	No limit
`BOLTZPAY_MONTHLY_BUDGET`	Monthly spending cap in USD	No limit
`BOLTZPAY_PER_TRANSACTION`	Per-request spending cap in USD	No limit
`BOLTZPAY_NETWORK`	`base` or `base-sepolia`	`base`
`BOLTZPAY_LOG_LEVEL`	`debug`, `info`, `warn`, `error`, `silent`	`warn`

MCP Transport (Outgoing Payments)

To pay other MCP servers that require payment, use wrapMcpClient() in your code. This is separate from the BoltzPay MCP server. See the MCP Transport guide.

Troubleshooting

”Tool not found” or no hammer icon

Claude Desktop didn’t load the MCP server. Check:

The JSON config is valid (no trailing commas, correct braces).
The file is at the correct path for your OS.
You restarted Claude Desktop after editing the config.

”npx fails” or “command not found”

Node.js is not in Claude Desktop’s PATH.

macOS: Install Node.js via the official installer (not just nvm). Or use the full path: "command": "/usr/local/bin/npx".
Windows: Use the cmd wrapper: "command": "cmd", "args": ["/c", "npx", "-y", "@boltzpay/mcp"].

”MISSING_CREDENTIALS” error

The boltzpay_fetch tool requires Coinbase keys to make payments. Read-only tools (quote, discover, diagnose) work without credentials. To enable payments, add the three COINBASE_* env vars to your config.

”BUDGET_EXCEEDED” error

You’ve hit your configured spending limit. Ask Claude to run boltzpay_budget to see the current state, or increase the limit in your config and restart.

Payments work but responses are empty

Some endpoints only accept POST requests. Ask Claude to use method: "POST" with the appropriate body. Check the endpoint’s documentation for the correct method.

​Quick Start

​Enable Payments

​Credential requirements

​Budget Control

​Tools

​boltzpay_fetch

​boltzpay_quote

​boltzpay_discover

​boltzpay_budget

​boltzpay_history

​boltzpay_diagnose

​boltzpay_wallet

​Error Handling

​Environment Variables

​MCP Transport (Outgoing Payments)

​Troubleshooting

​”Tool not found” or no hammer icon

​”npx fails” or “command not found”

​”MISSING_CREDENTIALS” error

​”BUDGET_EXCEEDED” error

​Payments work but responses are empty

Quick Start

Enable Payments

Credential requirements

Budget Control

Tools

boltzpay_fetch

boltzpay_quote

boltzpay_discover

boltzpay_budget

boltzpay_history

boltzpay_diagnose

boltzpay_wallet

Error Handling

Environment Variables

MCP Transport (Outgoing Payments)

Troubleshooting

”Tool not found” or no hammer icon

”npx fails” or “command not found”

”MISSING_CREDENTIALS” error

”BUDGET_EXCEEDED” error

Payments work but responses are empty