Victory Lucky for Afriex

Posted on May 2

Build Cross-Border Payment AI Agents with the Afriex MCP Server

#ai #agents #mcp #afriex

Payment integrations are straightforward until they are not. A single payout involves checking a balance, resolving a bank code, verifying an account number, looking up a live exchange rate, and then executing the transaction — each step a separate API call, each one requiring code you write and maintain.

The Afriex MCP server lets an AI agent handle that entire sequence through natural language. It exposes the complete Afriex Business API as 22 callable tools — customers, transactions, payment methods, exchange rates, and balances — that any MCP-compatible client can discover and use without SDK wiring.

Connect it to Claude Desktop, Claude Code, or Cursor and your AI assistant can register customers, attach bank accounts and mobile money wallets, fetch live NGN/KES/GHS rates, and trigger cross-border payouts — all from a single prompt.

If you are not yet familiar with Model Context Protocol and how it works, this article covers the protocol, architecture, and security model before you continue here.

The 22 tools

The server endpoint is https://mcp.afriex.com/mcp. Full reference at docs.afriex.com/mcp/introduction.

Authentication

Tool	What it does
`authenticate`	Sets your API key and environment for the session
`session_info`	Returns current session config — masked API key, environment, base URL

Customers

Tool	What it does
`create_customer`	Creates a customer with name, email, phone, and country code
`list_customers`	Returns a paginated list of customers
`get_customer`	Fetches a customer by ID
`delete_customer`	Deletes a customer by ID
`update_customer_kyc`	Updates KYC information for a customer

Transactions

Tool	What it does
`create_transaction`	Creates a `DEPOSIT`, `WITHDRAW`, or `SWAP` transaction
`list_transactions`	Returns a paginated list of transactions
`get_transaction`	Fetches a transaction by ID

Payment methods

Tool	What it does
`create_payment_method`	Creates a payment method: `BANK_ACCOUNT`, `SWIFT`, `MOBILE_MONEY`, `UPI`, `INTERAC`, `WE_CHAT`
`list_payment_methods`	Returns a paginated list of payment methods
`get_payment_method`	Fetches a payment method by ID
`delete_payment_method`	Deletes a payment method by ID
`list_institutions`	Lists banks and mobile money providers by country and channel
`resolve_institution_codes`	Resolves a SWIFT code or routing number to a bank name
`resolve_payment_method`	Resolves recipient info by account number or phone
`get_crypto_wallet`	Gets or creates a USDT/USDC crypto wallet (production only)
`get_virtual_account`	Gets or creates a virtual account (production only)

Organization

Tool	What it does
`get_balance`	Fetches wallet balances for specified currencies
`get_rates`	Gets live exchange rates across supported corridors
`topup_balance`	Tops up sandbox balance (development only)

Connecting your client

You will need an Afriex Business API key from the dashboard. Pass it via HTTP headers — this keeps credentials out of the conversation context and authenticates every tool call automatically.

Claude Desktop

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

{
  "mcpServers": {
    "afriex": {
      "url": "https://mcp.afriex.com/mcp",
      "headers": {
        "x-afriex-api-key": "your-api-key",
        "x-afriex-environment": "development"
      }
    }
  }
}

Restart Claude Desktop. The Afriex tools will appear in the tools panel.

Claude Code

Add to .claude/settings.json in your project:

{
  "mcpServers": {
    "afriex": {
      "url": "https://mcp.afriex.com/mcp",
      "headers": {
        "x-afriex-api-key": "your-api-key",
        "x-afriex-environment": "development"
      }
    }
  }
}

Or via the CLI:

claude mcp add afriex --transport http https://mcp.afriex.com/mcp

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "afriex": {
      "url": "https://mcp.afriex.com/mcp",
      "headers": {
        "x-afriex-api-key": "your-api-key",
        "x-afriex-environment": "development"
      }
    }
  }
}

Or go to Cursor Settings → MCP → Add new MCP Server, set type to URL, and enter https://mcp.afriex.com/mcp.

Without HTTP headers

If your client does not support custom headers, connect to the server URL without them and use the authenticate tool as your first prompt:

"Authenticate with API key your-api-key in the production environment."

The server stores your credentials for the session and uses them for all subsequent tool calls.

What you can build

Cross-border payout agent

A complete payout as an MCP tool chain:

list_institutions — resolve the correct bank or mobile money code for the recipient's country
create_customer — register the recipient
update_customer_kyc — complete KYC
resolve_payment_method — verify the account number before attaching it
create_payment_method — attach the verified bank account or mobile wallet
get_rates — preview the live exchange rate
get_balance — confirm sufficient funds before committing
create_transaction with type: "WITHDRAW" — execute the payout
get_transaction — poll settlement status

The agent chains these in sequence and branches on results — it will not call create_transaction if get_balance returns insufficient funds. You state the intent, the model decides the sequence.

Payroll disbursement agent

An agent that reads a payroll file and disburses to each employee across multiple African corridors:

get_rates per currency corridor to confirm converted amounts upfront
get_balance to verify total funds before any disbursement starts
For each employee: list_customers to check if they exist, create_customer if not, create_payment_method if no payout method is on file
create_transaction per employee
get_transaction to confirm each settlement

If a customer already exists, the agent skips creation. If funds run short mid-run, it stops and reports before making the next call rather than failing silently.

Operational queries from your IDE

With the server connected in Claude Code or Cursor, you can query your Afriex account without leaving your editor:

"What is the current NGN to USD rate?" → get_rates
"List my last 10 transactions and flag any that failed" → list_transactions
"Check my USD and GBP balances" → get_balance
"What is GTBank Nigeria's institution code?" → list_institutions
"Top up my sandbox NGN balance by 500,000" → topup_balance

FX rate monitoring agent

An agent that watches a currency pair and acts when a target rate is hit:

get_rates on a schedule for a specific corridor
Compare against a configured threshold
When the rate crosses, trigger create_transaction or surface an alert

Useful for businesses that time cross-border settlements against rate movements rather than executing at arbitrary times.

Sandbox and environment

Set x-afriex-environment to development for sandbox testing. The topup_balance tool funds your sandbox wallet with any currency and amount, so you can test the full tool chain — customer creation through transaction settlement — without touching live funds.

Switch to production in the header when ready to go live.

MCP versus the Afriex SDK

They are not alternatives — they serve different layers.

Use the SDK for production applications: deterministic code paths, typed inputs and outputs, full error handling control, and integration with your own data layer. The freelancer payout platform tutorial is a complete walkthrough of that approach.

Use the MCP server when an AI model is doing the orchestrating: agentic workflows, internal natural language tools, IDE queries during development, and rapid prototyping before you formalize an integration.

Most production setups use both — the SDK for core application logic, the MCP server for the agentic layer on top.

Full tool reference and setup docs at docs.afriex.com/mcp.

DEV Community