AgenticBTC MCP Setup Guide

One canonical path: prove the policy with no account or funds, verify the public package, then connect an MCP client.

Updated: July 27, 2026

1. Prove the policy first

Open the public $10 Policy Demo. No account, package, API key, wallet, or funds are required.

Run both requests:

• $3 should be approved because it is within the $10 limit.
• $50 should be blocked because it exceeds the $10 limit.

The on-page audit trail should explain both results. This is the canonical first decision and the fastest way to understand what AgenticBTC enforces.

2. Verify the public package

Requirements:

• Node.js 18 or newer
• A terminal

Run:

npx --yes agenticbtc-mcp@latest --help

The command requires no AgenticBTC account and should list start, setup, server, and status.

Canonical public artifacts:

• npm: agenticbtc-mcp
• source: bkblocksolutions-rgb/agenticbtc-mcp
• license: MIT

The agentbtc-backend repository is the hosted service implementation. It is not the public package or customer install repository.

3. Get hosted-service credentials

To connect an MCP client to the hosted service:

1. Open agenticbtc.app.
2. Create or sign in to an owner account.
3. Use the dashboard's displayed owner-key workflow to create or copy an owner API key.
4. Store the key like a password. Do not put it in source control, chat messages, screenshots, or shared documents.

An owner key has administrative authority. Give a spending agent a scoped agent key when the workflow supports it.

4. Configure your MCP client

Use your client's normal MCP server configuration:

{
  "mcpServers": {
    "agenticbtc": {
      "command": "npx",
      "args": ["--yes", "agenticbtc-mcp@latest", "server"],
      "env": {
        "AGENTICBTC_API_URL": "https://agenticbtc.app",
        "AGENTICBTC_API_KEY": "your-owner-api-key"
      }
    }
  }
}

Restart or reload the MCP client, then use its normal tool-discovery view to confirm that the AgenticBTC server loaded.

Claude Desktop interactive setup

The package can write Claude Desktop's MCP configuration:

npx --yes agenticbtc-mcp@latest start
npx --yes agenticbtc-mcp@latest status

The wizard is specifically a Claude Desktop config writer. OpenClaw and other MCP clients should use their own MCP configuration mechanism with the canonical server command and environment variables above.

5. Connect a payment rail only when needed

No payment rail is required for the public policy demo or package verification. Connect NWC, Strike, Coinbase, LND, or another supported rail only before a real payment test.

For optional LND configuration:

{
  "AGENTICBTC_LND_HOST": "https://your-node.example:8080",
  "AGENTICBTC_LND_MACAROON": "your-scoped-hex-macaroon"
}

Use the least-privileged credential that supports the intended action. Never commit wallet credentials, macaroons, connection strings, or private keys.

Troubleshooting

npx or node is not found

Install the current Node.js LTS release from nodejs.org, reopen the terminal, and confirm:

node --version
npx --version

The MCP server does not appear

• Confirm the package help command succeeds.
• Confirm the JSON is valid.
• Confirm the client configuration uses agenticbtc-mcp@latest, not agentbtc-mcp, agenticbtc, or @agentbtc/mcp-server.
• Fully restart or reload the MCP client.
• Check the client's MCP logs for the first startup error.

Authentication fails

• Confirm the API URL is exactly https://agenticbtc.app.
• Confirm AGENTICBTC_API_KEY is set in the MCP server environment.
• Replace a lost or exposed key through the dashboard; do not reuse it.

The package works but a payment cannot execute

Package startup and policy enforcement do not prove that a live payment rail is configured. Confirm the selected rail is connected and that the request is inside the agent's policy limits before retrying.

Canonical reference

Maintainers should use docs/CANONICAL-INSTALL-PATH.md inside the service repository as the source of truth for package naming, repository metadata, URLs, install commands, and release consistency checks.