Adaptis MCP Server

A local Model Context Protocol (MCP) server for the Adaptis (MEG) payment gateway. It lets AI agents (Claude Desktop, Claude Code, Cursor, and any other MCP client) help you integrate with and operate against the Adaptis APIs using your own merchant credentials.

The server runs locally on your machine (stdio transport). Your Merchant Key never leaves your computer except inside signed requests sent directly to the Adaptis gateway — exactly like your own backend integration would.

Features

Gateway actions (call the Adaptis APIs directly):

Tool	Endpoint	Purpose
adaptis_create_payment_link	POST /payment-links	Create single-use or reusable payment links
adaptis_requery_transaction	POST /merchantrequery	Check the latest transaction status (max 7×/day per transaction, within 10 days)
adaptis_refund_transaction	POST /merchantrefund	Refund a transaction (disabled by default — see below)
adaptis_check_gateway_health	POST /gatewayhealthinquiry	Check payment option availability
adaptis_server_initiate_payment	POST /entry/ServerInitiate	Host-to-host actions: Capture (21), token charges, and more

Integration helpers (no network — generate signed artifacts):

Tool	Purpose
adaptis_generate_hosted_checkout	Signed auto-submit HTML form for /entry/adaptishosted
adaptis_generate_merchant_hosted_payload	Signed payload for /entry/merchanthosted (PCI DSS flows)
adaptis_generate_signature	Compute/debug the HMAC-SHA512 signature for any flow
adaptis_verify_callback_signature	Verify backend (BackendURL) callback signatures

Reference lookups (offline):

Tool	Purpose
adaptis_lookup_payment_ids	Payment method IDs (cards, FPX banks, eWallets)
adaptis_lookup_status_codes	TransactionStatusId (1000–2100) and RefundStatusId (3100–3900)
adaptis_lookup_error_codes	6-digit error code mapping + health check error codes
adaptis_list_test_data	Sandbox test cards and approve/decline behaviours

Prerequisites

• Node.js 18+
• Adaptis Merchant Code and Merchant Key (contact Adaptis support for sandbox credentials)

Installation

git clone https://github.com/fredericktvf/adaptis-mcp-server.git
cd adaptis-mcp-server
npm install
npm run build

Configuration

Variable	Required	Default	Description
ADAPTIS_MERCHANT_CODE	✓	–	Your merchant code
ADAPTIS_MERCHANT_KEY	✓	–	Your merchant key (keep secret)
ADAPTIS_ENVIRONMENT	–	sandbox	sandbox (pay.meglabox.com) or production (pay.adaptispay.com)
ADAPTIS_ENABLE_REFUNDS	–	false	Set true to expose adaptis_refund_transaction
ADAPTIS_TOOLS	–	all	Comma-separated tool whitelist (least privilege)
ADAPTIS_TIMEOUT	–	60000	Gateway request timeout (ms)

Claude Desktop / Claude Code

Add to claude_desktop_config.json (Settings → Developer → Edit Config), or .mcp.json for Claude Code:

{
  "mcpServers": {
    "adaptis": {
      "command": "node",
      "args": ["/path/to/adaptis-mcp-server/dist/index.js"],
      "env": {
        "ADAPTIS_MERCHANT_CODE": "MMXXXXXX",
        "ADAPTIS_MERCHANT_KEY": "<<YOUR_MERCHANT_KEY>>",
        "ADAPTIS_ENVIRONMENT": "sandbox",
        "ADAPTIS_ENABLE_REFUNDS": "false",
        "ADAPTIS_TOOLS": "all"
      }
    }
  }
}

Cursor

Settings → Tools & MCP → Add MCP Server, using the same JSON block.

Example production config (least privilege)

"env": {
  "ADAPTIS_MERCHANT_CODE": "MMXXXXXX",
  "ADAPTIS_MERCHANT_KEY": "<<LIVE_KEY>>",
  "ADAPTIS_ENVIRONMENT": "production",
  "ADAPTIS_TOOLS": "adaptis_requery_transaction,adaptis_check_gateway_health,adaptis_lookup_status_codes,adaptis_lookup_error_codes"
}

Usage examples

Ask your AI client things like:

• "Create a MYR 150 payment link for invoice INV-2044, expiring end of this month, and email it to the customer."
• "Requery transaction ADP20260712093000 for 1.00 — did it go through?"
• "Why am I getting error 100004 on my requery call? Here's my base string..."
• "Generate the hosted checkout form for a RM 25 test payment."
• "Which payment methods are down right now?"
• "Verify this backend callback: TransId TR2529..., RefNo ..., Amount 1.00, Status 1, Signature ..."

Security notes

• Sandbox by default. Production must be enabled explicitly.
• Refunds are opt-in. adaptis_refund_transaction moves money and only exists when ADAPTIS_ENABLE_REFUNDS=true. Your AI client will additionally ask for confirmation (the tool is marked destructive).
• Tool whitelisting. Use ADAPTIS_TOOLS to expose only what you need, following least privilege.
• Merchant key masking. Debug outputs (raw signature base strings) mask your merchant key.
• Card data. Merchant Hosted and card-based Server Initiate flows carry PANs. Use sandbox test cards for integration; real card handling requires PCI DSS compliance.
• Callbacks. Always verify callback signatures (adaptis_verify_callback_signature), reply RECEIVEOK, and requery to independently confirm before fulfilling orders.

Signature formulas (reference)

Flow	Raw signature (then HMAC-SHA512 with MerchantKey)
Adaptis Hosted	Key + Code + RefNo + Amount + Currency
Merchant Hosted	Key + Code + RefNo + Amount + Currency + CardNumber + CardExpiryYear + CardExpiryMonth + CardCVV
Server Initiate (21 Capture)	Key + Code + RefNo + TransId + Amount + Currency
Server Initiate (others)	same as Merchant Hosted
Payment Link	Key + Code + ReferenceNumber + Amount + Currency + ExpiryDate (digits, if provided)
Requery	Key + Code + RefNo + Amount
Refund	Key + Code + IpayId + RefNo + RefundAmount + RefundCurrency
Gateway Health	Key + Code
Backend Callback	Key + Code + TransId + RefNo + Amount + Currency + Status

Amounts are stripped of dots/commas before signing (1.00 → 100).

Troubleshooting

"Unable to reach Adaptis gateway: fetch failed" — but the gateway works from your browser/PowerShell:

Node's fetch may be trying an IPv6 route your network can't complete. Add this line to the env block of your MCP config, then fully restart your MCP client:

"NODE_OPTIONS": "--dns-result-order=ipv4first"

Other causes: corporate proxy with TLS inspection (set NODE_EXTRA_CA_CERTS to your proxy's CA certificate), or a firewall blocking node.exe. The error message includes a [cause: ...] detail naming the exact network failure.

Config changes don't take effect — MCP servers launch once at client startup. Fully quit the app (on Windows: system tray → right-click → Quit), then relaunch. Closing the window is not enough.

Error 100004 Signature Failed — use adaptis_generate_signature to compare base strings. The most common mistakes: amount not stripped of separators (1.00 must sign as 100), or wrong field order.

Sandbox returns 503 — the sandbox gateway (pay.meglabox.com) is only available during business hours (MYT). Production is 24/7.

Development

npm run dev      # run from source with tsx
npm run build    # compile to dist/
npx @modelcontextprotocol/inspector node dist/index.js   # interactive testing

Support

Refer to the Adaptis Developer Portal (/developer/simulator/meg/) for the interactive API console, test data, and the full API reference.