# MCP · 让 AI 直接用 blockwallets

> blockwallets 的远程 MCP server:Claude、ChatGPT、Cursor、Codex 里直接查接入文档、建测试单、查订单和余额。没有任何能把钱转出去的工具。

让 Claude、ChatGPT、Cursor、Codex 直接查文档、建测试单、查订单。它只能收款和读数据,不能把钱转出去。

## 两个地址

- `https://blockwallets.io/mcp` (需要登录): OAuth 登录授权,或带后台生成的 MCP 令牌。全部工具。
- `https://blockwallets.io/mcp/public` (免登录): 只有文档、网络、价格、签名演示、接入清单这些公开工具。

## 一句话:在 AI 里接入、调试、查账。

- 写接入代码时,AI 直接查我们的文档和签名规则,不用你复制粘贴。
- 用测试令牌让 AI 建一张测试单、模拟付款,再查状态,把整条链路跑通。
- 日常问一句“昨天收了多少”“order_1042 付了没”,AI 帮你查。

## 复制一段,贴进你的工具。

令牌在后台「开发者 › AI 工具(MCP)」生成,明文只显示一次。先用 test 令牌。

### Claude Code

用令牌;或去掉 --header,进 Claude Code 后输入 /mcp 走登录授权。

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

### Claude Code · 只用文档工具(免登录)

```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

令牌放环境变量 BLOCKWALLETS_MCP_TOKEN;需要支持 HTTP MCP 的新版 Codex。

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

## Claude 和 ChatGPT:登录授权就行。

### Claude(网页版 / 桌面版)

1. 设置 → 连接器 → 添加自定义连接器
2. 名称填 blockwallets,URL 填 https://blockwallets.io/mcp
3. 点连接,在弹出的页面登录 blockwallets 商户后台
4. 在授权页选测试或正式模式、是否允许建单,点同意

### ChatGPT

1. 设置 → 应用与连接器 → 高级设置,打开开发者模式
2. 创建连接器,URL 填 https://blockwallets.io/mcp,认证方式选 OAuth
3. 登录 blockwallets 商户后台
4. 在授权页选模式和权限,点同意

不想登录?URL 填 https://blockwallets.io/mcp/public,只能用公开的文档工具。

## 11 个工具,没有一个能转出钱。

| 工具 | 做什么 | 权限 |
|---|---|---|
| `search_docs` | 搜接入文档,返回相关段落和链接 | 公开 |
| `get_doc` | 读文档的某一节(Markdown) | 公开 |
| `list_networks` | 支持的币和网络、确认数、最低金额 | 公开 |
| `get_pricing` | 费率和阶梯 | 公开 |
| `explain_signature` | 逐步演示签名怎么算(不收 API key) | 公开 |
| `integration_checklist` | 按你的技术栈给接入步骤和验收清单 | 公开 |
| `create_payment` | 建一张账单,拿付款页链接(同 order_id 幂等) | payments:create |
| `create_payment_link` | 建一个收款链接和二维码 | payments:create |
| `get_payment` | 按 order_id / uuid 查一张账单 | read |
| `list_payments` | 按状态、时间列账单 | read |
| `get_balance` | 看 live 余额(只看,不能提现) | read |

## 只能收,不能转。

- **没有资金流出的工具**: 提现、出款、退款、改提现地址、改回调地址、改密钥,MCP 里都没有,权限里也没有。这些只能你在后台操作。
- **先用测试模式**: test 令牌只在测试网上建单、只看测试数据,不涉及真钱。
- **正式模式建议只读**: live 凭据能看到真实订单和余额。不需要建单就只给 read。开了两步验证的账户,建 live 凭据要输验证码,还会发邮件提醒。
- **随时吊销**: 手动令牌和 OAuth 授权在后台同一个列表里,点一下吊销,正在用的令牌立刻失效。
- **只存哈希**: 令牌和授权码只存 sha256,明文只在生成时显示一次。每次调用记审计,每个凭据每分钟最多 60 次。

## 常见问题

### MCP 是什么?

Model Context Protocol,让 AI 工具调用外部服务的开放协议。接上以后,Claude、ChatGPT、Cursor 这些工具能直接调 blockwallets 的工具。

### AI 能用它把我的钱转走吗?

不能。MCP 里没有任何提现、出款、退款或改地址、改密钥的工具,权限里也不存在这类操作。

### 测试模式和正式模式有什么区别?

测试模式跑在公共测试网上,建的单、看的数据都是测试的;正式模式是你的真实账户。建议先用测试模式把流程跑通。

### Cursor 能用 OAuth 登录吗?

现在 Cursor 请用后台生成的令牌。OAuth 登录支持 Claude、ChatGPT、Claude Code 这类使用 https 或本机回调地址的客户端。

### 怎么撤销授权?

后台「开发者 › AI 工具(MCP)」里找到对应的令牌或授权,点吊销,立刻生效。

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