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

Video hướng dẫn

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.
• 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.

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: "*".

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

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 · Tài liệu cho AI agent · Sandbox