WorldFirst Server

MCP server that gives AI agents access to WorldFirst cross-border payment APIs. Built for the Model Context Protocol.

What it does

Lets any MCP-compatible AI agent (Claude, OpenAI, LangChain, etc.) autonomously:

• Check balances across 20+ currencies in your World Account
• Get FX quotes and lock rates for cross-currency payments
• Manage suppliers — add, list, and verify beneficiaries
• Make payments — send CNY to Chinese suppliers with same-day settlement
• Pull statements — transaction history for reconciliation and auditing

Tools

Tool	Description
check_balance	Query World Account balances by currency
get_fx_rate	Get indicative FX rate (informational)
get_fx_quote	Get tradeable FX quote with price and expiry
lock_fx_rate	Accept a quote and lock the rate
list_beneficiaries	List saved suppliers/payees
add_beneficiary	Register a new supplier for payments
verify_supplier	Verify supplier bank account against business registration
create_payment	Send payment to a registered beneficiary
check_payment_status	Track payment settlement status
get_statement	Pull transaction history with date/currency filters

Setup

1. Get WorldFirst API credentials

Contact WorldFirst to get:

• Client ID — your partner identifier
• RSA key pair — generate locally, share public key with WorldFirst

# Generate RSA key pair
openssl genrsa -out private_key.pem 2048
openssl rsa -in private_key.pem -pubout -out public_key.pem
# Send public_key.pem to WorldFirst Technical Support

2. Install

npm install worldfirst-mcp-server

3. Configure in Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "worldfirst": {
      "command": "npx",
      "args": ["worldfirst-mcp-server"],
      "env": {
        "WORLDFIRST_CLIENT_ID": "your_client_id",
        "WORLDFIRST_PRIVATE_KEY": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
        "WORLDFIRST_ENVIRONMENT": "sandbox",
        "WORLDFIRST_REGION": "sg"
      }
    }
  }
}

4. Configure in Claude Code

claude mcp add worldfirst -- npx worldfirst-mcp-server

Set environment variables:

export WORLDFIRST_CLIENT_ID=your_client_id
export WORLDFIRST_PRIVATE_KEY="$(cat private_key.pem)"
export WORLDFIRST_ENVIRONMENT=sandbox
export WORLDFIRST_REGION=sg

Environment Variables

Variable	Required	Default	Description
WORLDFIRST_CLIENT_ID	Yes	—	Your WorldFirst Client ID
WORLDFIRST_PRIVATE_KEY	Yes	—	RSA private key (PEM format)
WORLDFIRST_ENVIRONMENT	No	sandbox	sandbox or production
WORLDFIRST_REGION	No	sg	sg, eu, or us

Example: AI agent pays a Chinese supplier

Agent: "Pay our Shenzhen electronics supplier $5,000 USD worth of CNY"

1. check_balance(currency: "USD")           → $12,450 available
2. get_fx_quote(sell: "USD", buy: "CNY")    → 1 USD = 7.24 CNY, expires in 30s
3. lock_fx_rate(quote_id: "Q123")           → Rate locked
4. verify_supplier(beneficiary_id: "B456")  → Verified ✓
5. create_payment(amount: "36200.00",
     currency: "CNY", beneficiary: "B456",
     quote: "Q123")                          → Payment initiated
6. check_payment_status(payment: "P789")    → Settled (same-day)

Development

git clone <repo>
cd worldfirst-mcp-server
npm install
npm run dev    # Run with tsx (hot reload)
npm run build  # Compile TypeScript

License

MIT