> Cài monapay-mcp, đưa API key cho Claude Code, Cursor hoặc Codex, rồi tạo link thu tiền, tra giao dịch và thử webhook ngay trong khung chat.

Nguồn: https://monapay.vn/docs/mcp · Cập nhật: 2026-09-18

[Lấy API key miễn phí](https://my.monapay.vn/auth?mode=register)

Dùng ngay

- [Dùng ngay, không cần lập trình](https://monapay.vn/docs/dung-ngay)
- [Quán ăn, quán trà sữa](https://monapay.vn/docs/dung-ngay/quan-an-tra-sua)
- [Tiệm tóc, spa](https://monapay.vn/docs/dung-ngay/tiem-toc-spa)
- [Bán hàng online](https://monapay.vn/docs/dung-ngay/ban-hang-online)
- [Lớp học, trung tâm](https://monapay.vn/docs/dung-ngay/lop-hoc)

Bắt đầu

- [Tổng quan](https://monapay.vn/docs)
- [Bắt đầu nhanh (5 phút)](https://monapay.vn/docs/bat-dau-nhanh)
- [Khái niệm: VA, VietQR, webhook](https://monapay.vn/docs/khai-niem)

Theo stack

- [Site tĩnh Astro/Hugo + serverless](https://monapay.vn/docs/stack/astro-static-serverless)
- [Django / FastAPI](https://monapay.vn/docs/stack/django-fastapi)
- [Express / NestJS](https://monapay.vn/docs/stack/express-nestjs)
- [Flutter / React Native](https://monapay.vn/docs/stack/flutter-react-native)
- [Go / Spring Boot / .NET](https://monapay.vn/docs/stack/go-java-dotnet)
- [Google Sheets tự ghi tiền vào (Google Apps Scrip](https://monapay.vn/docs/stack/google-apps-script)
- [Laravel nhận VietQR, package PHP](https://monapay.vn/docs/stack/laravel)
- [Build bằng AI builder (Lovable/Bolt/v0/Replit)](https://monapay.vn/docs/stack/lovable-bolt-v0-replit)
- [n8n](https://monapay.vn/docs/stack/n8n)
- [Next.js (App Router, Vercel) nhận chuyển khoản t](https://monapay.vn/docs/stack/nextjs)
- [Supabase Edge Function nhận webhook, cập nhật bả](https://monapay.vn/docs/stack/supabase)
- [WordPress tự viết form, không WooCommerce](https://monapay.vn/docs/stack/wordpress-khong-woo)

Công thức cho agent

- [AI agent bán dịch vụ tự thu tiền rồi mới trả kết](https://monapay.vn/docs/cong-thuc/ai-agent-tu-thu-tien)
- [Bán khoá học, ebook, file số](https://monapay.vn/docs/cong-thuc/ban-khoa-hoc-file-so)
- [App đặt lịch thu cọc](https://monapay.vn/docs/cong-thuc/booking-thu-coc)
- [Bot Telegram/Zalo bán hàng](https://monapay.vn/docs/cong-thuc/bot-telegram-zalo-ban-hang)
- [Cá nhân, hộ kinh doanh chưa có công ty](https://monapay.vn/docs/cong-thuc/ca-nhan-chua-co-cong-ty)
- [Khách chuyển thiếu, thừa, sai nội dung](https://monapay.vn/docs/cong-thuc/khop-don-thieu-thua-sai-noi-dung)
- [App có ví](https://monapay.vn/docs/cong-thuc/nap-vi-cong-credit)
- [Nền tảng nhiều shop, mỗi shop nhận tiền vào tài](https://monapay.vn/docs/cong-thuc/platform-nhieu-shop)
- [SaaS gói tháng thu bằng chuyển khoản](https://monapay.vn/docs/cong-thuc/saas-thu-phi-thang)
- [Landing tĩnh trên Vercel/Netlify, không backend](https://monapay.vn/docs/cong-thuc/site-tinh-khong-backend)
- [Stripe không mở cho Việt Nam](https://monapay.vn/docs/cong-thuc/stripe-khong-ho-tro-viet-nam-dev)
- [Test webhook ở máy mình](https://monapay.vn/docs/cong-thuc/test-local-ngrok-sandbox)
- [Nhận tiền xong tự xuất hoá đơn điện tử và gửi em](https://monapay.vn/docs/cong-thuc/thu-tien-xong-xuat-hoa-don-gui-email)
- [Web bán hàng](https://monapay.vn/docs/cong-thuc/web-ban-hang-tu-xac-nhan-don)

Webhooks

- [Tích hợp webhook](https://monapay.vn/docs/webhooks/tich-hop-webhook)
- [Định dạng payload](https://monapay.vn/docs/webhooks/dinh-dang-payload)
- [Bảo mật: HMAC + chống replay](https://monapay.vn/docs/webhooks/bao-mat)
- [Gửi lại và xử lý lỗi](https://monapay.vn/docs/webhooks/gui-lai-va-xu-ly-loi)
- [Đối soát giao dịch](https://monapay.vn/docs/webhooks/doi-soat)

API v1

- [Xác thực](https://monapay.vn/docs/api/xac-thuc)
- [API keys](https://monapay.vn/docs/api/api-keys)
- [Sandbox: thử không tốn tiền](https://monapay.vn/docs/api/sandbox)
- [Tài khoản ảo (VA)](https://monapay.vn/docs/api/tai-khoan-ao-va)
- [QR thanh toán](https://monapay.vn/docs/api/qr-thanh-toan)
- [Trang thanh toán](https://monapay.vn/docs/api/trang-thanh-toan)
- [Giao dịch](https://monapay.vn/docs/api/giao-dich)
- [Cấu hình webhook qua API](https://monapay.vn/docs/api/webhook-configs)
- [Gói và hoá đơn (billing)](https://monapay.vn/docs/api/goi-va-hoa-don)

Cho lập trình viên

- [MCP server](https://monapay.vn/docs/mcp)
- [SDK](https://monapay.vn/docs/sdk)
- [Mã nguồn GitHub](https://monapay.vn/docs/github)

Kênh thông báo

- [Telegram](https://monapay.vn/docs/telegram)
- [Zalo](https://monapay.vn/docs/zalo)
- [Email](https://monapay.vn/docs/email)

Tham chiếu

- [API reference tương tác](https://monapay.vn/docs/api-reference)
- [Địa chỉ IP](https://monapay.vn/docs/dia-chi-ip)
- [Dành cho AI agent](https://monapay.vn/docs/ai-agent)

[MONA Pay](https://monapay.vn/)[Tài liệu](https://monapay.vn/docs)MCP server MONA Pay: cho Claude Code, Cursor, Codex thu tiền thay bạn

# MCP server MONA Pay: cho Claude Code, Cursor, Codex thu tiền thay bạn

Cập nhật 05/09/2026[Bản Markdown](https://monapay.vn/docs/mcp.md)[llms.txt](https://monapay.vn/llms.txt)[openapi.json](https://monapay.vn/openapi.json)

## Video hướng dẫn

Cài MCP MONA Pay từ npm cho Claude Code, Codex, Cursor: 47 công cụ thu tiền cho AI agent · [Xem trên YouTube](https://www.youtube.com/watch?v=-MiSYhObank)

**Xem transcript video (8 phần)**

### Thu tiền ngay trong IDE

Bạn đang dùng Claude Code, Codex hoặc Cursor và muốn agent tự tạo QR, tra giao dịch, cấu hình webhook ngay trong lúc code. Nhưng đưa tài khoản đăng nhập cho agent vừa bất tiện, vừa vướng xác thực hai lớp. Trong video này, mình cài gói monapay-mcp từ npm, nối bằng khóa API và kiểm tra cách dùng bốn mươi bảy công cụ. Toàn bộ phần cài đặt chỉ cần Node mười tám trở lên và một tài khoản MONA Pay.

### Cài gói từ npm

Trước hết, mở my.monapay.vn, vào API Keys, bấm Tạo key và lưu client_id cùng client_secret. Mã bí mật chỉ hiện một lần, nên đặt trong biến môi trường, không ghi vào mã nguồn. Gói trên npm có tên chính xác là monapay-mcp. Lệnh npx monapay-mcp chạy máy chủ qua stdio. Khi thêm vào một trình khách MCP, README dùng npx -y monapay-mcp để npm tự xác nhận việc chạy gói.

### Cấu hình Claude Code

Với Claude Code, sao chép nguyên lệnh trong README. Hai tùy chọn -e truyền MONAPAY_CLIENT_ID và MONAPAY_CLIENT_SECRET; phần sau dấu -- là lệnh khởi động MCP. Sau khi thêm, mở lại phiên làm việc nếu trình khách chưa nhận cấu hình mới. Cách này lấy OAuth token bằng client credentials, nên agent không cần username hay mật khẩu. Tài khoản bật xác thực hai lớp vẫn dùng được bình thường.

### Cấu hình Codex Cursor

Cursor dùng tệp .cursor/mcp.json, còn Codex dùng ~/.codex/config.toml. Với Codex, tạo mục [mcp_servers.monapay], đặt command là npx, args là -y và monapay-mcp, rồi khai báo hai biến môi trường. Claude Desktop dùng cấu trúc mcpServers tương tự Cursor. Kiểm tra cấu hình xong bằng cách yêu cầu agent đọc hồ sơ tài khoản hiện tại. Dù dùng trình khách nào, không commit giá trị thật của MONAPAY_CLIENT_SECRET vào git và không dán secret vào prompt công khai.

### Bốn mươi bảy tool

Khi kết nối xong, agent có bốn mươi bảy tool chia theo công việc. Nhóm đọc hồ sơ và tài khoản có monapay_whoami, monapay_me, danh sách ngân hàng và VA. Nhóm thu tiền tạo checkout, tạo VietQR, tra giao dịch và tạo giao dịch sandbox. Nhóm vận hành tạo, sửa, thử webhook, đọc log và thống kê. Ngoài ra còn nhóm email, Zalo, xoay khóa, kiểm chữ ký và sinh code endpoint webhook cho PHP, Node hoặc Python.

### Nối ngân hàng bằng OTP

Agent còn có thể nối tài khoản ACB bằng bốn bước có hai điểm dừng. Nó gọi monapay_link_bank_start, rồi phải hỏi bạn OTP lần đầu trước khi gọi monapay_link_bank_verify_otp. Tiếp theo, agent đăng ký thông báo bằng monapay_notification_register, hỏi OTP lần hai và mới gọi monapay_notification_verify_otp. Nếu OTP sai hoặc hết hạn, gọi lại bước trước để ngân hàng gửi mã mới. Agent không được tự đoán hoặc lưu OTP.

### Giao agent tích hợp

Một yêu cầu thực tế có thể bắt đầu bằng câu: tích hợp nhận tiền chuyển khoản cho web này bằng MONA Pay. Agent kiểm tài khoản, lấy code mẫu nhận webhook, viết endpoint, đăng ký cấu hình HMAC, bắn thử và đọc log để chắc endpoint trả HTTP hai trăm. Sau đó nó tạo checkout cho từng đơn và chờ sự kiện CHECKOUT_PAID. Với webhook, chữ ký phải được kiểm trên raw body và transaction_code phải là khóa chống xử lý trùng.

### Sửa lỗi và mở docs

Nếu MCP không lên, kiểm tra Node đã từ phiên bản mười tám, tên gói là monapay-mcp và đủ hai biến môi trường. Nếu vừa xoay khóa, secret cũ hết hiệu lực ngay; cập nhật MONAPAY_CLIENT_SECRET rồi khởi động lại agent. Hướng dẫn đầy đủ nằm ở trang npm và monapay.vn/docs/ai-agent. Bạn có thể đăng ký tại my.monapay.vn. Khi cần hỗ trợ, gọi một chín không không, sáu ba sáu, sáu bốn tám.

`monapay-mcp` là MCP server chính thức của MONA Pay. Sau khi cài, Claude Code, Cursor, Codex hoặc một MCP client khác có thể gọi 50 công cụ để tạo link thu tiền, tạo VietQR, tra giao dịch, cấu hình webhook và chạy sandbox ngay trong lúc làm code.

Tiền vẫn chuyển thẳng vào tài khoản ngân hàng của bạn. MCP chỉ dùng API MONA Pay để tạo và đọc dữ liệu theo lệnh bạn giao.

## Chuẩn bị

- Node.js 18 trở lên.
- Tài khoản MONA Pay tại [my.monapay.vn](https://my.monapay.vn).
- Một khối cấu hình lấy từ dashboard: **API Keys → Tạo key → Đưa cho AI agent**.

Khối này có `client_id` và `client_secret`. Agent dùng hai giá trị đó để lấy Bearer token qua OAuth client credentials. Agent không cầm username hoặc mật khẩu, nên tài khoản bật xác thực 2 lớp vẫn dùng được.

Secret chỉ nên nằm trong biến môi trường hoặc cấu hình MCP trên máy của bạn. Không dán secret vào source, ảnh chụp, issue GitHub hoặc tin nhắn công khai.

## Chạy thử từ terminal

Package trên npm có tên chính xác là `monapay-mcp` và cần Node.js 18 trở lên:

```
npx monapay-mcp
```

Server dùng giao tiếp `stdio`. Khi chạy qua một MCP client, dùng `npx -y monapay-mcp` để client tự khởi động đúng package.

| Biến môi trường | Dùng để làm gì |
| --- | --- |
| `MONAPAY_CLIENT_ID` | ID của API key trong dashboard |
| `MONAPAY_CLIENT_SECRET` | Secret của API key, dùng lấy OAuth token và ký quyền cho lệnh ghi |
| `MONAPAY_BASE_URL` | Tuỳ chọn, mặc định `https://api.monapay.vn` |

`MONAPAY_USERNAME` và `MONAPAY_PASSWORD` là cách tương thích cũ. Đội MONA khuyên dùng `client_id` và `client_secret`; cách dùng mật khẩu sẽ không chạy khi tài khoản bật xác thực 2 lớp.

## Cấu hình Claude Code

Chép nguyên khối dashboard cấp cho bạn, hoặc thay hai giá trị mẫu dưới đây:

```
claude mcp add monapay \
  -e MONAPAY_CLIENT_ID=client_id_cua_anh_chi \
  -e MONAPAY_CLIENT_SECRET=client_secret_cua_anh_chi \
  -- npx -y monapay-mcp
```

Mở lại Claude Code nếu client chưa nhận server, sau đó yêu cầu: `Kiểm tra kết nối MONA Pay của tôi`. MCP sẽ gọi `monapay_whoami`.

## Cấu hình Cursor

Tạo hoặc cập nhật `.cursor/mcp.json` trong dự án:

```
{
  "mcpServers": {
    "monapay": {
      "command": "npx",
      "args": ["-y", "monapay-mcp"],
      "env": {
        "MONAPAY_CLIENT_ID": "client_id",
        "MONAPAY_CLIENT_SECRET": "client_secret"
      }
    }
  }
}
```

Nếu file này chứa secret thật, thêm nó vào `.gitignore` trước khi commit. Khởi động lại Cursor rồi kiểm tra server `monapay` trong danh sách MCP.

## Cấu hình Codex

Thêm vào `~/.codex/config.toml`:

```
[mcp_servers.monapay]
command = "npx"
args = ["-y", "monapay-mcp"]
env = { MONAPAY_CLIENT_ID = "client_id", MONAPAY_CLIENT_SECRET = "client_secret" }
```

Khởi động lại Codex sau khi lưu. Nếu bạn xoay secret trong dashboard hoặc bằng tool `monapay_rotate_key`, hãy cập nhật `MONAPAY_CLIENT_SECRET` rồi khởi động lại client.

## Các công cụ MCP

Mỗi tool trong manifest có nhãn phạm vi để client biết đây là lệnh đọc hay lệnh ghi. Các nhãn như `read`, `checkout:write`, `webhooks:write` mô tả loại thao tác của tool; OAuth token hiện trả `scope: "*"`.

| Nhóm | Tool |
| --- | --- |
| Bắt đầu nhanh | `monapay_quickstart` |
| Kết nối và hồ sơ | `monapay_whoami`, `monapay_me` |
| Ngân hàng và VA | `monapay_list_bank_accounts`, `monapay_list_virtual_accounts`, `monapay_link_bank_start`, `monapay_link_bank_verify_otp`, `monapay_notification_register`, `monapay_notification_verify_otp` |
| Hồ sơ thanh toán | `monapay_get_payment_profile`, `monapay_set_payment_profile` |
| Link thu tiền | `monapay_create_checkout`, `monapay_get_checkout`, `monapay_list_checkouts`, `monapay_cancel_checkout` |
| VietQR | `monapay_create_qr`, `monapay_cancel_qr` |
| Giao dịch | `monapay_list_transactions`, `monapay_get_transaction`, `monapay_get_transactions_summary`, `monapay_sandbox_transaction`, `monapay_retry_transaction` |
| Webhook | `monapay_list_webhooks`, `monapay_create_webhook`, `monapay_update_webhook`, `monapay_delete_webhook`, `monapay_test_webhook`, `monapay_webhook_logs`, `monapay_webhook_stats` |
| Email | `monapay_list_email_configs`, `monapay_create_email_config`, `monapay_update_email_config`, `monapay_delete_email_config`, `monapay_verify_email`, `monapay_resend_email_verification`, `monapay_test_email`, `monapay_email_logs`, `monapay_email_stats`, `monapay_list_email_suppressions`, `monapay_remove_email_suppression` |
| Nhóm Zalo | `monapay_list_zalo_groups`, `monapay_create_zalo_group`, `monapay_update_zalo_group`, `monapay_delete_zalo_group`, `monapay_test_zalo_group`, `monapay_zalo_group_logs` |
| API key | `monapay_generate_key`, `monapay_rotate_key` |
| Chạy tại máy | `monapay_verify_signature`, `monapay_generate_webhook_snippet` |

MCP còn có resource `monapay://docs/llms`, `monapay://docs/{slug}` và prompt `integrate-monapay`. Tool `monapay_verify_signature` chạy tại máy, không gọi mạng.

## Những câu bạn có thể giao thẳng cho AI

**1. “Tạo link thu 250.000đ cho đơn DH10234 và chạy ở sandbox.”**

Agent gọi `monapay_create_checkout` với `amount: 250000`, `order_code: "DH10234"`, `sandbox: true`, rồi trả `checkout_url`. Khi cần kiểm lại, agent gọi `monapay_get_checkout`.

**2. “Tra 20 giao dịch mới nhất của tài khoản ảo MONA0000010234.”**

Agent gọi `monapay_list_transactions` với số VA, trang 1 và giới hạn 20. Đây là lệnh đọc, phù hợp để đối soát mà không đổi cấu hình.

**3. “Tạo webhook HMAC cho shop này, bắn thử và kiểm tra log giúp tôi.”**

Agent có thể lấy code bằng `monapay_generate_webhook_snippet`, tạo cấu hình bằng `monapay_create_webhook`, gọi `monapay_test_webhook`, rồi đọc `monapay_webhook_logs`. Bạn chỉ nên chốt xong khi endpoint trả HTTP 200, 201 hoặc 202.

## Chỗ agent phải dừng để hỏi bạn

- Nối ACB có 2 mã OTP do ngân hàng gửi về điện thoại. Agent phải hỏi bạn ở cả hai bước, không được đoán mã.
- Thêm địa chỉ nhận email có mã xác minh 6 số. Agent phải chờ bạn đọc mã trong hộp thư.
- Nhóm Zalo cần `group_id` thật và đã có bot Gấu Mona.

Các tool ghi tự gửi `X-Client-Secret` khi đã cấu hình `MONAPAY_CLIENT_SECRET`. Dùng một API key riêng cho từng máy hoặc từng dự án để có thể thu hồi đúng chỗ khi secret bị lộ. Khi nghi lộ secret, gọi `monapay_rotate_key`, cập nhật cấu hình rồi khởi động lại MCP client; secret cũ hết hiệu lực ngay.

## Lỗi thường gặp

| Hiện tượng | Cách kiểm |
| --- | --- |
| MCP client không thấy server | Chạy `node --version`, cần từ 18; chạy `npx -y monapay-mcp` trong terminal để xem lỗi khởi động |
| `monapay_whoami` trả 401 | Chép lại đúng cặp `client_id` và `client_secret` từ cùng một API key |
| Lệnh ghi bị từ chối | Kiểm `MONAPAY_CLIENT_SECRET`, khởi động lại client sau khi xoay key |
| Webhook test thất bại | URL phải public qua HTTPS; đọc `monapay_webhook_logs` để xem HTTP code và thời gian phản hồi |

## Cài MCP MONA Cloud qua 5 cửa AI

### Claude Code

Chạy trong terminal.

```
claude mcp add --transport http monacloud https://mcp.monacloud.vn/mcp
```

### Claude.ai (người bấm)

Vào Settings → Connectors → Add custom connector. Điền tên và URL, bấm Add rồi đăng nhập MONA Pass.

```
Name: MONA Cloud\nURL: https://mcp.monacloud.vn/mcp
```

### Codex

Thêm vào `~/.codex/config.toml`.

```
[mcp_servers.monacloud]\nurl = "https://mcp.monacloud.vn/mcp"
```

### Gemini (Antigravity)

Chạy trong terminal. Cấu hình lưu tại `~/.gemini/config/mcp_config.json`; kiểm tra bằng `agy mcp list`.

```
agy mcp add monacloud https://mcp.monacloud.vn/mcp
```

### Cursor

Thêm vào `.cursor/mcp.json`.

```
{ "mcpServers": { "monacloud": { "url": "https://mcp.monacloud.vn/mcp" } } }
```

### Giao thẳng cho AI tự cài

```
Cài MCP MONA Cloud giúp tôi rồi kiểm tra chạy được chưa. Nếu bạn là Claude Code: chạy `claude mcp add --transport http monacloud https://mcp.monacloud.vn/mcp`. Nếu là Codex: thêm `[mcp_servers.monacloud]` với `url = "https://mcp.monacloud.vn/mcp"` vào `~/.codex/config.toml`. Nếu là Gemini/Antigravity: chạy `agy mcp add monacloud https://mcp.monacloud.vn/mcp`. Cài xong gọi thử `cloud_domain_search` với tên tôi muốn mua rồi báo giá cho tôi.
```

Qua endpoint chung, đăng nhập MONA Pass rồi gọi `monapay_link` một lần. Muốn dùng API key riêng thì chạy tại máy bằng `npx -y monapay-mcp`.

Đặc tả đầy đủ: [MCP manifest](https://monapay.vn/.well-known/mcp-manifest.json) · [Tài liệu cho AI agent](https://monapay.vn/docs/ai-agent) · [Sandbox](https://monapay.vn/docs/api/sandbox)

Trong trang này

- Video hướng dẫn
- Chuẩn bị
- Chạy thử từ terminal
- Cấu hình Claude Code
- Cấu hình Cursor
- Cấu hình Codex
- Các công cụ MCP
- Những câu bạn có thể giao thẳng cho AI
- Chỗ agent phải dừng để hỏi bạn
- Cài MCP MONA Cloud qua 5 cửa AI
- Lỗi thường gặp