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):

Integration helpers (no network — generate signed artifacts):

Reference lookups (offline):

Related MCP server: btcpay-mcp

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

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)

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, or a corporate proxy is intercepting TLS. Add these lines to the env block of your MCP config, then fully restart your MCP client:

"NODE_OPTIONS": "--dns-result-order=ipv4first",
"NODE_TLS_REJECT_UNAUTHORIZED": "0"

• NODE_OPTIONS: --dns-result-order=ipv4first — fixes IPv6-preference failures (most common on Windows).

• NODE_TLS_REJECT_UNAUTHORIZED: "0" — accepts the proxy's self-signed certificate when a corporate proxy/antivirus performs TLS inspection. ⚠️ This disables TLS certificate validation for the MCP server process, which weakens security. Prefer NODE_EXTRA_CA_CERTS pointing at your proxy's CA certificate where possible, and only keep NODE_TLS_REJECT_UNAUTHORIZED=0 on machines behind a trusted corporate proxy.

Try NODE_OPTIONS alone first; add NODE_TLS_REJECT_UNAUTHORIZED only if you still see certificate errors in the [cause: ...] detail. A firewall blocking node.exe produces ECONNREFUSED/timeouts instead.

"Invalid Request (BillingAddress... is required)" on Adaptis Hosted / Merchant Hosted — the live gateway requires BillingAddressLine1, BillingAddressState, BillingAddressCity, BillingAddressPostalCode, and BillingAddressCountry on payment requests. The checkout tools enforce these as required inputs.

"100002 Invalid Request (Invalid PaymentType)" on Payment Link — PaymentType accepts only Card, EWallet, OnlineBanking, Instalment (comma-separated). "PaymentType Unavailable" means that category is not enabled for your merchant profile.

Empty page after payment redirect — the ResponseURL/BackendURL sent in the request must be the merchant's real endpoints. Never use placeholder/demo URLs.

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.