Build Cross-Border Payment AI Agents with the Afriex MCP Server
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.
Loading comments…