movmint-fx-mcp

MCP server for the Movmint FX quoting and capture service. Exposes two tools (get_fx_quote, capture_fx_quote) that LLM clients can call to get live FX rates and execute trades.

---

Architecture

How it fits together

┌─────────────────────────────────────────────────────────────────┐
│  LLM Client (Claude Desktop / Open WebUI + Ollama)              │
└───────────────────────┬─────────────────────────────────────────┘
                        │
          ┌─────────────▼──────────────┐
          │  Transport layer           │
          │                            │
          │  Option A: stdio           │  ← Claude Desktop spawns
          │    (no port, no proxy)     │    the process directly
          │                            │
          │  Option B: HTTP via mcpo   │  ← Open WebUI / Ollama
          │    localhost:8008          │    connects as tool server
          └─────────────┬──────────────┘
                        │
          ┌─────────────▼──────────────┐
          │  MCP Server (Node.js)      │
          │  src/index.ts              │
          │                            │
          │  Tools:                    │
          │  • get_fx_quote            │
          │  • capture_fx_quote        │
          └─────────────┬──────────────┘
                        │  OAuth2 client_credentials
                        │  Bearer token (cached, auto-refreshed)
          ┌─────────────▼──────────────┐
          │  Movmint API               │
          │  api.nextgen.digitalfiat.app│
          │                            │
          │  POST /fx/quote            │
          │  POST /fx/quote/capture/:id│
          └────────────────────────────┘

MCP Server (src/index.ts)

Written in TypeScript using the @modelcontextprotocol/sdk. Key behaviours:

• Transport: StdioServerTransport — communicates over stdin/stdout. Does not bind to a network port by itself.
• Auth: OAuth2 client_credentials flow. Tokens are cached in memory and refreshed 30 seconds before expiry.
• Validation: Tool inputs are validated with zod schemas before the API is called.

Tool: get_fx_quote

Calls POST /fx/quote on the Movmint API.

Parameter	Type	Required	Description
from_currency	string	Yes	Source currency code (e.g. BSD, USD)
to_currency	string	Yes	Target currency code (e.g. USDC, EUR)
amount	number	Yes	Amount in from_currency
funding_method	IMMEDIATE | DEFERRED	No	Defaults to IMMEDIATE
tx_configuration	object	Yes	Client reference ID + source/target payment config
participants	array	No	KYC participants (ULTIMATE_ORIGINATOR, ULTIMATE_BENEFICIARY, etc.)

Returns a quote_id valid for approximately 30 seconds.

Tool: capture_fx_quote

Calls POST /fx/quote/capture/{quote_id} on the Movmint API.

Parameter	Type	Required	Description
quote_id	string	Yes	The quote_id returned from get_fx_quote

Returns transaction details including the deposit address for funding.

Payment configuration schemas

tx_configuration accepts source_configuration and target_configuration, each with a source_type and an account_configuration that is one of:

Type	Fields
BANK_ACCOUNT	account_number, routing_number, account_type (CHECKING/SAVINGS)
DLT_WALLET	wallet_address, network (ethereum/solana/base/sanddollar)
CARD	card_number, expiry_date, cvv, cardholder_name, card_type (CreditCard/DebitCard)

---

Environment variables

Variable	Default	Required
CLIENT_ID	—	Yes
CLIENT_SECRET	—	Yes
MOVMINT_BASE_URL	https://api.nextgen.digitalfiat.app	No
MOVMINT_TOKEN_URL	https://api.nextgen.digitalfiat.app/oauth2/token	No
MOVMINT_TOKEN_AUDIENCE	fx-service	No

Store these in a .env file at the project root (never commit it — it is gitignored).

CLIENT_ID=your-client-id
CLIENT_SECRET=your-client-secret
MOVMINT_BASE_URL=https://api.nextgen.digitalfiat.app
MOVMINT_TOKEN_URL=https://api.nextgen.digitalfiat.app/oauth2/token
MOVMINT_TOKEN_AUDIENCE=fx-service

---

Bootstrap: running locally

Prerequisites

• Node.js 20+
• uvx (ships with uv) — for running mcpo without a permanent install

1. Install dependencies and build

cd /path/to/movmint-fx-mcp
npm install
npm run build        # compiles src/ → dist/

2. Option A — Claude Desktop (stdio, no proxy needed)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "movmint-fx": {
      "command": "node",
      "args": ["/absolute/path/to/movmint-fx-mcp/dist/index.js"],
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Restart Claude Desktop. The tools appear automatically in the tool picker.

2. Option B — Open WebUI + Ollama (HTTP via mcpo)

mcpo is a proxy that wraps any stdio MCP server and exposes it as an OpenAI-compatible HTTP tool server. Open WebUI can then connect to it as a tool source for any hosted model including Ollama models.

Port map (confirmed on this machine)

Service	Port
Ollama	11434
Open WebUI	8080
mcpo (this server)	8008

Step 1 — Create mcpo-config.json

Create mcpo-config.json at the project root (it is gitignored):

{
  "mcpServers": {
    "movmint-fx": {
      "command": "node",
      "args": ["/absolute/path/to/movmint-fx-mcp/dist/index.js"],
      "env": {
        "CLIENT_ID": "your-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "MOVMINT_BASE_URL": "https://api.nextgen.digitalfiat.app",
        "MOVMINT_TOKEN_URL": "https://api.nextgen.digitalfiat.app/oauth2/token",
        "MOVMINT_TOKEN_AUDIENCE": "fx-service"
      }
    }
  }
}

Step 2 — Start mcpo

uvx mcpo --port 8008 --config /absolute/path/to/movmint-fx-mcp/mcpo-config.json

Verify it is running:

curl http://localhost:8008/docs        # OpenAPI/Swagger UI
curl http://localhost:8008/openapi.json

Step 3 — Connect Open WebUI

1. Open WebUI → Admin Panel → Settings → Tools
2. Add tool server URL: http://localhost:8008
3. Open WebUI discovers get_fx_quote and capture_fx_quote automatically via the OpenAPI spec
4. Enable the tools when starting a chat with any Ollama model

3. Development mode (watch + rebuild)

npm run dev      # tsc --watch, rebuilds dist/ on every save

Run mcpo in a separate terminal; it will pick up the rebuilt dist/index.js on the next tool invocation (the Node process is spawned fresh per mcpo request).

---

Project structure

movmint-fx-mcp/
├── src/
│   └── index.ts          # MCP server — tools, auth, API client
├── dist/                 # Compiled output (gitignored)
├── interactions/
│   └── SD-CAD_SD-USD Collection.postman_collection.json
├── mcpo-config.json      # mcpo proxy config with credentials (gitignored)
├── package.json
├── tsconfig.json
├── .env                  # Local credentials (gitignored)
└── .gitignore

---

Security notes

• mcpo-config.json and .env both contain credentials and are gitignored. Do not commit either file.
• The MCP server logs the token request URL and body to stderr for debugging. Avoid piping stderr to shared log aggregators in production.
• The quote_id returned by get_fx_quote expires in ~30 seconds. Do not store or reuse stale quote IDs.