vn.monapay/monapay-mcp

monapay-mcp

An MCP server that lets AI coding agents such as Claude Code, Cursor and Codex (or any MCP client) work with MONA Pay while coding: link a bank account, create checkout links and VietQR codes, look up incoming transfers, configure and test webhooks, email and Zalo group notifications, and verify webhook signatures.

Published on npm as monapay-mcp and in the MCP Registry as vn.monapay/monapay-mcp.

Install

Requires Node.js 18 or later and a MONA Pay API key (client ID and client secret, created in the MONA Pay dashboard).

npx -y monapay-mcp   # starts the server over stdio

Claude Code

claude mcp add monapay \
  -e MONAPAY_CLIENT_ID=your_client_id \
  -e MONAPAY_CLIENT_SECRET=your_client_secret \
  -- npx -y monapay-mcp

Cursor (.cursor/mcp.json) and Claude Desktop (claude_desktop_config.json)

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

Codex (~/.codex/config.toml)

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

Configuration

Client credentials are recommended over username/password, because accounts with 2FA enabled cannot log in with a password.

Usage

Tools

Resources and prompt

• monapay://docs/llms: machine-readable index of the MONA Pay docs.
• monapay://docs/{slug}: one docs page as Markdown, for example monapay://docs/webhooks/tich-hop-webhook.
• Prompt integrate-monapay (arguments language, framework): a 6-step plan for the agent to integrate MONA Pay into the current project.

Example

"Integrate automatic bank transfer confirmation into this Laravel site with MONA Pay."

The agent calls monapay_whoami, gets receiver code with monapay_generate_webhook_snippet(language="php"), writes the endpoint into the project, registers it with monapay_create_webhook(auth_type="HMAC_SHA256", secret_key=...), fires monapay_test_webhook, reads monapay_webhook_logs to confirm the endpoint returns 200, then uses monapay_create_checkout for each order and waits for CHECKOUT_PAID.

Link a bank account with OTP

ACB sends each OTP to the account holder's registered phone. The agent must ask the user at steps 2 and 4 and never guess an OTP.

1. Call monapay_link_bank_start with the ACB account number, phone number, customer type, VA prefix and identifier. It returns acb_request_id, and ACB sends the first OTP.
2. Ask the user for the OTP and call monapay_link_bank_verify_otp. It returns virtual_account_id and the VA number.
3. Call monapay_notification_register with virtual_account_id. ACB sends the second OTP.
4. Ask the user for the second OTP and call monapay_notification_verify_otp. Incoming transfers are now forwarded to your configured webhooks.

If an OTP is wrong or expired, call the previous step again to get a new code.

Zalo group notifications

The group must contain the MONA bot (Gấu Mona), which is added by the MONA team. group_id is 10 to 25 digits and comes from MONA Account/PMS.

Call monapay_create_zalo_group with group_id, a friendly name and the events to receive: TRANSACTION_IN, CHECKOUT_PAID, WEBHOOK_FAILED, VA_CREATED. You can limit it to one virtual_account_id, send a test with monapay_test_zalo_group and check delivery with monapay_zalo_group_logs.

Zalo does not render Markdown, so message_template must be plain text. It supports {amount}, {description}, {virtual_account_number}, {transaction_code} and {transfer_date}; the {{amount}} form also works.

Key rotation

monapay_rotate_key uses the current secret to rotate the key that matches MONAPAY_CLIENT_ID. The old secret stops working immediately; update MONAPAY_CLIENT_SECRET in your MCP config and restart the client.

Webhook signature

X-Mona-Signature: sha256=<hex>, where hex = HMAC-SHA256(secret, "<X-Mona-Timestamp>.<raw_body>"). Reject requests whose timestamp is more than 300 seconds off and compare in constant time. transaction_code stays the same across retries, so use it as the deduplication key.

Development

npm install
npm test     # build + node --test

# Calls a few read-only tools against a real account
MONAPAY_CLIENT_ID=... MONAPAY_CLIENT_SECRET=... MONAPAY_BASE_URL=https://api.monapay.vn npm run smoke

Agent guide: https://monapay.vn/ai-agent · Documentation: https://monapay.vn/docs

License

MIT

MONA Pay is part of MONA Cloud by The MONA Group.