# Adaptis MCP Server

A local [Model Context Protocol](https://modelcontextprotocol.io) (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

```bash
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:

```json
{
  "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)

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

```json
"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

```bash
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.