# MCP · Use blockwallets from your AI tools

> The blockwallets remote MCP server: search the integration docs, create test invoices, check orders and balances from Claude, ChatGPT, Cursor and Codex. No tool can move money out.

Let Claude, ChatGPT, Cursor and Codex read the docs, create test invoices and check orders for you. It can only collect payments and read data. It cannot move money out.

## Two URLs

- `https://blockwallets.io/mcp` (Sign-in required): OAuth sign-in, or a Bearer MCP token from the dashboard. All tools.
- `https://blockwallets.io/mcp/public` (No sign-in): Public tools only: docs, networks, pricing, signature walkthrough, integration checklist.

## In short: integrate, debug and check your books from your AI.

- While you write the integration, your AI reads our docs and signature rules directly, no copy-paste.
- With a test token, your AI creates a test invoice, you simulate the payment, and it checks the status end to end.
- Day to day, ask “how much did we take yesterday?” or “is order_1042 paid?” and get an answer.

## Copy one snippet into your tool.

Create tokens in the dashboard under “Developers › AI tools (MCP)”; the token is shown once. Start with a test token.

### Claude Code

With a token; or drop --header and run /mcp inside Claude Code to sign in with OAuth.

```bash
claude mcp add --transport http blockwallets https://blockwallets.io/mcp \
  --header "Authorization: Bearer bw_mcp_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

### Claude Code · docs tools only (no sign-in)

```bash
claude mcp add --transport http blockwallets-docs https://blockwallets.io/mcp/public
```

### Cursor · ~/.cursor/mcp.json

```json
{
  "mcpServers": {
    "blockwallets": {
      "url": "https://blockwallets.io/mcp",
      "headers": {
        "Authorization": "Bearer bw_mcp_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### Windsurf · ~/.codeium/windsurf/mcp_config.json

```json
{
  "mcpServers": {
    "blockwallets": {
      "serverUrl": "https://blockwallets.io/mcp",
      "headers": {
        "Authorization": "Bearer bw_mcp_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

### Codex · ~/.codex/config.toml

Put the token in the BLOCKWALLETS_MCP_TOKEN environment variable; needs a recent Codex with HTTP MCP support.

```toml
[mcp_servers.blockwallets]
url = "https://blockwallets.io/mcp"
bearer_token_env_var = "BLOCKWALLETS_MCP_TOKEN"
```

## Claude and ChatGPT: just sign in.

### Claude (web / desktop)

1. Settings → Connectors → Add custom connector
2. Name it blockwallets and use the URL https://blockwallets.io/mcp
3. Click Connect and sign in to your blockwallets dashboard in the page that opens
4. On the consent page pick test or live mode and whether to allow creating invoices, then Allow

### ChatGPT

1. Settings → Apps & Connectors → Advanced, turn on Developer mode
2. Create a connector with the URL https://blockwallets.io/mcp and OAuth authentication
3. Sign in to your blockwallets dashboard
4. Pick the mode and permissions on the consent page and Allow

Don't want to sign in? Use https://blockwallets.io/mcp/public for the public docs tools only.

## 11 tools, none can send money out.

| Tool | What it does | Permission |
|---|---|---|
| `search_docs` | Search the integration docs; returns matching sections and links | public |
| `get_doc` | Read one docs section as Markdown | public |
| `list_networks` | Coins and networks, confirmations, minimum amounts | public |
| `get_pricing` | Fees and volume tiers | public |
| `explain_signature` | Step-by-step signature walkthrough (never takes an API key) | public |
| `integration_checklist` | Integration steps and acceptance checklist for your stack | public |
| `create_payment` | Create an invoice and get its payment page (idempotent by order_id) | payments:create |
| `create_payment_link` | Create a payment link and QR code | payments:create |
| `get_payment` | Read one invoice by order_id or uuid | read |
| `list_payments` | List invoices by status and date | read |
| `get_balance` | Read the live balance (read only, no withdrawals) | read |

## It collects. It never sends.

- **No tool moves money out**: Withdrawals, payouts, refunds, withdrawal addresses, callback URLs and keys are not in MCP and have no permission. Only you can do them in the dashboard.
- **Start in test mode**: Test credentials only create invoices on testnets and only see test data. No real money.
- **Keep live read-only**: Live credentials see real orders and balances. Grant read only unless you need to create invoices. Accounts with two-factor need a code for live credentials, and we email you each time.
- **Revoke any time**: Tokens and OAuth grants share one list in the dashboard. Revoke one and its tokens stop working immediately.
- **Hashes only**: Tokens and codes are stored as sha256; a token is shown once. Every merchant call is audited, and each credential is limited to 60 requests per minute.

## FAQ

### What is MCP?

The Model Context Protocol, an open standard for AI tools to call external services. Once connected, Claude, ChatGPT, Cursor and others can call blockwallets tools directly.

### Can an AI use it to take my money?

No. There is no tool for withdrawals, payouts, refunds, or changing addresses or keys, and no permission for them exists.

### What is the difference between test and live?

Test mode runs on public testnets with test invoices and data; live is your real account. Get the flow working in test mode first.

### Does Cursor support OAuth sign-in?

For now, use a dashboard token in Cursor. OAuth works with clients that use https or loopback redirects, such as Claude, ChatGPT and Claude Code.

### How do I revoke access?

Find the token or grant in the dashboard under “Developers › AI tools (MCP)” and revoke it; it takes effect immediately.

OAuth metadata: https://blockwallets.io/.well-known/oauth-protected-resource · https://blockwallets.io/.well-known/oauth-authorization-server