# MCP · Dùng blockwallets ngay trong công cụ AI

> MCP server từ xa của blockwallets: tra tài liệu tích hợp, tạo hóa đơn thử nghiệm, kiểm tra đơn và số dư ngay trong Claude, ChatGPT, Cursor và Codex. Không công cụ nào chuyển được tiền ra ngoài.

Để Claude, ChatGPT, Cursor và Codex đọc tài liệu, tạo hóa đơn thử nghiệm và kiểm tra đơn hàng giúp bạn. Nó chỉ nhận tiền và đọc dữ liệu, không thể chuyển tiền ra ngoài.

## Hai địa chỉ

- `https://blockwallets.io/mcp` (Cần đăng nhập): Đăng nhập OAuth, hoặc token MCP (Bearer) tạo trong trang quản trị. Đủ mọi công cụ.
- `https://blockwallets.io/mcp/public` (Không cần đăng nhập): Chỉ công cụ công khai: tài liệu, mạng, bảng giá, minh họa chữ ký, danh sách tích hợp.

## Tóm lại: tích hợp, gỡ lỗi và xem sổ sách ngay trong AI.

- Khi bạn viết code tích hợp, AI đọc thẳng tài liệu và quy tắc chữ ký của chúng tôi, không phải sao chép dán.
- Với token thử nghiệm, AI tạo hóa đơn thử, bạn mô phỏng thanh toán, rồi nó kiểm tra trạng thái từ đầu đến cuối.
- Hằng ngày, hỏi “hôm qua thu được bao nhiêu?” hay “order_1042 đã trả chưa?” là có câu trả lời.

## Sao chép một đoạn vào công cụ của bạn.

Tạo token trong trang quản trị tại “Nhà phát triển › Công cụ AI (MCP)”; token chỉ hiện một lần. Hãy bắt đầu bằng token thử nghiệm.

### Claude Code

Dùng token; hoặc bỏ --header rồi chạy /mcp trong Claude Code để đăng nhập bằng OAuth.

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

### Claude Code · chỉ công cụ tài liệu (không cần đăng nhập)

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

Đặt token vào biến môi trường BLOCKWALLETS_MCP_TOKEN; cần bản Codex mới có hỗ trợ MCP qua HTTP.

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

## Claude và ChatGPT: chỉ cần đăng nhập.

### Claude (web / máy tính)

1. Cài đặt → Trình kết nối → Thêm trình kết nối tùy chỉnh
2. Đặt tên blockwallets và dùng URL https://blockwallets.io/mcp
3. Bấm Kết nối và đăng nhập trang quản trị blockwallets ở trang vừa mở
4. Ở trang cấp quyền, chọn chế độ thử nghiệm hay thật và có cho tạo hóa đơn không, rồi bấm Cho phép

### ChatGPT

1. Cài đặt → Ứng dụng & Trình kết nối → Nâng cao, bật Chế độ nhà phát triển
2. Tạo trình kết nối với URL https://blockwallets.io/mcp và xác thực OAuth
3. Đăng nhập trang quản trị blockwallets
4. Chọn chế độ và quyền ở trang cấp quyền rồi bấm Cho phép

Không muốn đăng nhập? Dùng https://blockwallets.io/mcp/public để chỉ dùng các công cụ tài liệu công khai.

## 11 công cụ, không cái nào chuyển được tiền ra.

| Công cụ | Làm gì | Quyền |
|---|---|---|
| `search_docs` | Tìm trong tài liệu tích hợp; trả về đoạn liên quan và liên kết | công khai |
| `get_doc` | Đọc một mục tài liệu dạng Markdown | công khai |
| `list_networks` | Coin và mạng, số xác nhận, số tiền tối thiểu | công khai |
| `get_pricing` | Phí và các bậc doanh số | công khai |
| `explain_signature` | Minh họa từng bước cách tính chữ ký (không bao giờ nhận API key) | công khai |
| `integration_checklist` | Các bước tích hợp và danh sách nghiệm thu cho công nghệ bạn dùng | công khai |
| `create_payment` | Tạo hóa đơn và lấy trang thanh toán (idempotent theo order_id) | payments:create |
| `create_payment_link` | Tạo liên kết thanh toán và mã QR | payments:create |
| `get_payment` | Xem một hóa đơn theo order_id hoặc uuid | read |
| `list_payments` | Liệt kê hóa đơn theo trạng thái và ngày | read |
| `get_balance` | Xem số dư live (chỉ đọc, không rút được) | read |

## Chỉ nhận. Không bao giờ gửi.

- **Không công cụ nào chuyển tiền ra**: Rút tiền, chi trả, hoàn tiền, địa chỉ rút, URL callback và khóa đều không có trong MCP và không có quyền tương ứng. Chỉ bạn làm được trong trang quản trị.
- **Bắt đầu ở chế độ thử nghiệm**: Thông tin xác thực thử nghiệm chỉ tạo hóa đơn trên testnet và chỉ thấy dữ liệu thử. Không có tiền thật.
- **Để live ở chế độ chỉ đọc**: Thông tin xác thực live thấy đơn hàng và số dư thật. Chỉ cấp quyền đọc trừ khi cần tạo hóa đơn. Tài khoản bật xác thực hai lớp phải nhập mã khi tạo thông tin live, và chúng tôi gửi email báo mỗi lần.
- **Thu hồi bất cứ lúc nào**: Token và quyền OAuth nằm chung một danh sách trong trang quản trị. Thu hồi là token ngừng hoạt động ngay.
- **Chỉ lưu hash**: Token và mã được lưu dưới dạng sha256; token chỉ hiện một lần. Mọi lệnh gọi của người bán đều được ghi nhật ký, và mỗi thông tin xác thực tối đa 60 yêu cầu mỗi phút.

## Hỏi đáp

### MCP là gì?

Model Context Protocol, một chuẩn mở để công cụ AI gọi dịch vụ bên ngoài. Sau khi kết nối, Claude, ChatGPT, Cursor và các công cụ khác gọi trực tiếp được công cụ của blockwallets.

### AI có thể dùng nó để lấy tiền của tôi không?

Không. Không có công cụ nào để rút tiền, chi trả, hoàn tiền hay đổi địa chỉ, đổi khóa, và cũng không tồn tại quyền nào cho việc đó.

### Chế độ thử nghiệm và thật khác nhau thế nào?

Chế độ thử nghiệm chạy trên testnet công khai với hóa đơn và dữ liệu thử; chế độ thật là tài khoản thật của bạn. Hãy chạy thông luồng ở chế độ thử nghiệm trước.

### Cursor có đăng nhập OAuth được không?

Hiện tại hãy dùng token từ trang quản trị trong Cursor. OAuth hoạt động với các ứng dụng dùng chuyển hướng https hoặc loopback, như Claude, ChatGPT và Claude Code.

### Làm sao thu hồi quyền truy cập?

Tìm token hoặc quyền đã cấp trong trang quản trị tại “Nhà phát triển › Công cụ AI (MCP)” và thu hồi; có hiệu lực ngay.

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