mexar-mcp-server

An exploratory Model Context Protocol server that exposes the MEXAR core API (money changer / CRM) to AI clients. It lets a user drive customer and transaction workflows through natural language, e.g.:

"Today I traded with Luke. Luke exchanged 1k USD for 32k THB."

This is a prototype (V1). It is intentionally biased toward read / lookup tools; the write tools exist but are confirm-gated (see below) because this is a real financial system.

Architecture

A thin TypeScript client over the existing REST API — no backend changes required. Authentication uses an existing Laravel Passport (OAuth2) bearer token supplied via environment variable. The token must belong to an employee-identity user who is a member of the departments being used.

src/
├── index.ts          # entry: build server, register tools, stdio transport
├── config.ts         # env: MEXAR_API_BASE_URL, MEXAR_ACCESS_TOKEN
├── client.ts         # fetch wrapper (bearer auth, error normalisation)
└── tools/
    ├── shared.ts     # result helpers + dry-run (confirm) gate
    ├── departments.ts
    ├── customers.ts
    ├── exchange.ts   # money changer
    └── remittance.ts

Tools

| Tool | Type | Endpoint | | --- | --- | --- | | list_my_departments | read | GET /me | | get_department_currencies | read | GET /departments/{id}/currencies | | search_customers | read | GET /crm/entities?condition=name&q= | | get_customer | read | GET /crm/entities/{id} | | quote_exchange | read | POST /departments/{id}/calc/exchange | | create_customer | write* | POST /crm/entities | | create_exchange | write* | POST /mc/create (money changer) | | create_remittance | write* | POST /remittance/create |

* Write tools are confirm-gated. They default to confirm: false, which returns a dry-run preview of the exact payload the tool would send — nothing is created. Call the tool again with confirm: true to actually execute. This keeps a human in the loop before any financial record is written.

Money changer vs remittance

• create_exchange (/mc/create): buy/sell of a foreign currency against the department base currency. The item has no target_currency_id. Use when one side of the trade is the base currency.
• create_remittance (/remittance/create): cross-currency / cross-border, item carries both source_currency_id and target_currency_id; requires kyc_screen + purpose_of_transfer.

Resolve the department's base_currency_id (via get_department_currencies) to decide which to use.

Setup

cp .env.example .env   # then fill in MEXAR_API_BASE_URL and MEXAR_ACCESS_TOKEN
npm install
npm run build

Run with Claude Code / Claude Desktop

Add to your MCP client config (adjust the absolute path):

{
  "mcpServers": {
    "mexar": {
      "command": "node",
      "args": ["/absolute/path/to/mexar-mcp-server/dist/index.js"],
      "env": {
        "MEXAR_API_BASE_URL": "https://your-mexar-host/api/v1",
        "MEXAR_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

For local iteration: npm run dev (runs src/index.ts directly via tsx).

Known limitations (V1)

• Rate semantics: the user's implied rate (e.g. 32) may differ from the system rate; the API may flag it as an override or reject it if exchange-rate verification is enabled. Always quote_exchange first.
• Duplicate customers: search_customers must be run before create_customer; the model should confirm with the user when results are ambiguous.
• Payments not settled: write tools create transactions in an open state; payment configuration (to_receives / to_sends) is left to the back office in this prototype.
• No retries / rate limiting / structured outputs yet.