Connect Chimoney to Claude: Manage Wallets, Rates & Global Payouts

If you are building autonomous financial agents to manage global payouts, query exchange rates, or disburse mobile money via Chimoney, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool-calling capabilities and Chimoney's REST API. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

If your team uses ChatGPT, check out our guide on connecting Chimoney to ChatGPT or explore our broader architectural overview on connecting Chimoney to AI Agents.

Giving a Large Language Model (LLM) write access to your corporate treasury or payout wallets is an intense engineering challenge. You have to map highly specific banking requirements for different countries into JSON schemas that an LLM can understand, manage asynchronous payout statuses, and handle strict rate limits. Every time Chimoney updates a required field for a regional bank transfer, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Chimoney, connect it natively to Claude Desktop, and execute complex cross-border financial workflows using natural language.

The Engineering Reality of the Chimoney API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools via JSON-RPC 2.0, building MCP servers against global payment APIs requires significant domain-specific logic.

If you decide to build a custom MCP server for Chimoney, you own the entire API lifecycle. Here are the specific challenges you will face:

Polymorphic and Country-Specific Validation Rules Global banking is fragmented. A bank payout via Chimoney to Nigeria might only require a bank code and account number. A bank payout to Kenya might require an additional branch_code. A transfer via PIX in Brazil requires entirely different identification fields. If you expose raw parameters to Claude without strict schema constraints, the model will hallucinate generic fields and the Chimoney API will reject the payload. Your MCP server must leverage Chimoney's dynamic beneficiary rule endpoints to feed the LLM the exact required schema for a specific country before it attempts a payout.

Asynchronous State and Reference Polling When you initiate a payout in Chimoney, you do not immediately get a "success" or "failed" status. You get a chiRef (a reference ID). The transaction enters a processing queue. To know if funds were successfully disbursed, your AI agent must explicitly poll the API using that reference ID. If you do not build this two-step pattern into your MCP tool descriptions, Claude will assume a 200 OK on the initial POST request means the money has hit the recipient's bank account, leading to dangerous logic errors.

Strict Rate Limits and Safe Idempotency Chimoney enforces strict rate limits to protect its infrastructure. A common mistake when building financial integrations is putting a black-box retry queue in front of the API. If a payout request times out or hits a rate limit, automated retries can accidentally trigger duplicate disbursements.

Truto does not retry, throttle, or apply backoff on rate limit errors. When Chimoney returns an HTTP 429 (Too Many Requests), Truto passes that exact error straight to the caller (your agent). Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Your agent is strictly responsible for reading these headers and executing its own backoff strategy, ensuring you retain total control over financial idempotency.

How to Generate a Chimoney MCP Server with Truto

Truto dynamically generates MCP tools from Chimoney's API documentation and your environment configurations. There is no code to write. You simply connect a Chimoney account and generate a tokenized URL.

Method 1: Via the Truto UI

For teams who want a zero-code setup, you can generate the server directly from the dashboard.

1. Log into Truto and navigate to the Integrated Accounts page.
2. Select your connected Chimoney account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read methods only, or set an expiration date).
6. Copy the generated MCP server URL (it will look like https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto API

For platform engineers building multi-tenant MCP servers for AI products, you can generate MCP servers programmatically. Make a POST request to /integrated-account/:id/mcp with your desired configuration.

curl -X POST "https://api.truto.one/integrated-account/YOUR_ACCOUNT_ID/mcp" \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Chimoney Treasury Agent",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The API validates that the integration has tools available, generates a cryptographically secure token, and returns a ready-to-use JSON-RPC URL.

{
  "id": "mcp_8a9b0c...",
  "name": "Production Chimoney Treasury Agent",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you can connect it to Claude. Because the URL contains an embedded cryptographic token, it is fully self-contained.

Method 1: Via the Claude UI (Web/Desktop)

If you are using Claude's graphical interface or custom connectors:

1. Copy the MCP server URL from Truto.
2. In Claude, navigate to Settings -> Connectors -> Add custom connector.
3. Paste the URL and click Add.
4. Claude will immediately handshake with the endpoint, fetch the JSON schemas for the Chimoney tools, and make them available to your agent.

(Note: If your team uses ChatGPT, the process is similar. Go to Settings -> Apps -> Advanced settings, enable Developer mode, and add the server URL under Custom Connectors).

Method 2: Via Manual Configuration File (Claude Desktop)

If you are running Claude Desktop locally and prefer file-based configuration, you can add the server using the official MCP Server SSE package.

Open your claude_desktop_config.json file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the following:

{
  "mcpServers": {
    "chimoney-treasury": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/YOUR_SECURE_TOKEN"
      ]
    }
  }
}

Restart Claude Desktop. The application will connect to the SSE transport and initialize the Chimoney tools.

Core Chimoney Tools for AI Agents

Truto exposes Chimoney's REST operations as distinct, well-documented MCP tools. Here are 6 high-leverage hero tools your AI agent can use to orchestrate global financial operations.

1. list_all_chimoney_info_exchange_rates

Before executing cross-border payouts, your agent needs to know the exact exchange rate Chimoney will use. This tool returns current currency pair rates (e.g., NGNUSD, USDAED) along with exact expiration timestamps.

"Check the current exchange rate for USD to Kenyan Shillings (KES) and tell me when that rate expires."

2. list_all_chimoney_info_beneficiary_rules

This is a critical gating tool for reliable AI execution. It allows the LLM to query the specific validation rules for a given country, preventing hallucinated banking parameters. It returns the required fields, their expected data types, and regex patterns for validation.

"What are the exact required bank fields and validation rules to send a payout to a bank account in Ghana?"

3. create_a_chimoney_payouts_bank

This tool executes a fiat bank transfer. It accepts an array of payload objects, allowing the LLM to batch multiple payouts in a single execution. The LLM must supply the destination country, bank codes, account numbers, and amounts.

"Initiate a bank payout of $500 to account number 123456789 at Equity Bank in Kenya using the branch code 068."

4. create_a_chimoney_payouts_mobile_money

Mobile money (MoMo) is the dominant financial rail in many emerging markets. This tool allows the agent to disburse funds directly to phone numbers via providers like MTN, Airtel, or M-Pesa.

"Disburse $50 via mobile money to the Ugandan phone number +256770000000. Use MTN as the provider code."

5. list_all_chimoney_multicurrency_wallets_gets

Your agent needs visibility into available liquidity before committing to transactions. This tool retrieves the detailed balances and transaction histories for a specific multicurrency wallet.

"Check the current balance of our primary USD multicurrency wallet (ID: 98765) to ensure we have enough funds for today's payroll run."

6. create_a_chimoney_payouts_status

Because payouts return a chiRef rather than an immediate settlement status, this tool is how your agent closes the loop. It checks the final processing state of a transaction.

"Check the processing status of the Chimoney payout with reference ID 'CHI-XYZ-123'. Let me know if it failed or succeeded."

For the complete inventory of Chimoney tools, schemas, and required parameters, review the Chimoney integration page.

Workflows in Action

Individual tools are useful, but the real power of connecting Chimoney to Claude lies in orchestrating multi-step financial workflows.

Scenario 1: Cross-Border Payroll Operations

Imagine an IT admin instructing an AI agent to execute a payroll run for a contractor in Kenya.

"Check our primary wallet balance (ID: 555) to ensure we have at least $2,000. If we do, find the required banking fields for a Kenyan payout, and then initiate a $2,000 transfer to account 0123456 at KCB Bank. Finally, give me the reference ID for the transaction."

Execution Steps:

1. Claude calls list_all_chimoney_multicurrency_wallets_gets to verify available liquidity in the specified wallet.
2. Claude calls list_all_chimoney_info_beneficiary_rules with country_code: "KE" to discover that Kenya requires a branch_code.
3. Claude calls create_a_chimoney_payouts_bank with the properly constructed payload array, including the required branch code.
4. Claude reads the resulting chiRef from the response and outputs it to the user.

sequenceDiagram
    participant User
    participant Agent as Claude Desktop
    participant MCP as Truto MCP Server
    participant API as Chimoney API
    
    User->>Agent: "Check balance, get Kenya rules, send $2000..."
    Agent->>MCP: tools/call (list_all_chimoney_multicurrency_wallets_gets)
    MCP->>API: GET /v0.2/wallets/multicurrency?id=555
    API-->>MCP: { "balance": 15000.00 }
    MCP-->>Agent: Wallet data
    
    Agent->>MCP: tools/call (list_all_chimoney_info_beneficiary_rules)
    MCP->>API: GET /v0.2/info/beneficiary-rules?country_code=KE
    API-->>MCP: { "required": ["account_number", "branch_code"] }
    MCP-->>Agent: Schema rules
    
    Agent->>MCP: tools/call (create_a_chimoney_payouts_bank)
    MCP->>API: POST /v0.2/payouts/bank
    API-->>MCP: { "chiRef": "CHI-KEN-999" }
    MCP-->>Agent: Transaction initialized
    Agent-->>User: "Transfer initiated. Reference: CHI-KEN-999"

Scenario 2: Mobile Money Disbursement & Verification

Sometimes a user needs the agent to execute a fast disbursement and actively wait to ensure it settles.

"Disburse $15 to phone number +256770000000 in Uganda via MTN mobile money. Once submitted, check the status using the reference ID to confirm it successfully processed."

Execution Steps:

1. Claude calls create_a_chimoney_payouts_mobile_money formatting the payload with countryToSend: "UG", momoCode: "MTN", and the provided phone number.
2. The tool returns a chiRef indicating the disbursement is processing.
3. Claude uses that reference ID to immediately call create_a_chimoney_payouts_status.
4. Claude informs the user that the funds have cleared the gateway.

Security and Access Control

Giving an AI agent access to a financial API requires strict boundary controls. Truto MCP servers support highly granular security configurations built directly into the server URL:

• Method Filtering (config.methods): You can lock down an MCP server to specific operation types. For example, setting methods: ["read"] ensures the agent can query exchange rates and wallet balances, but physically cannot invoke create endpoints to move money.
• Tag Filtering (config.tags): You can restrict access to specific operational domains. If you only want an agent to handle airtime disbursements, you can filter tools to only include those tagged with airtime.
• Extra Authentication (require_api_token_auth): By default, possessing the MCP URL grants access. By setting this flag to true, the connecting client must also supply a valid Truto API token in the Authorization header, preventing unauthorized execution if the URL leaks into log files.
• Time-to-Live (expires_at): You can generate temporary, short-lived MCP servers for ephemeral workflows. Once the timestamp passes, the underlying token is destroyed and the server instantly stops responding.

Automate Global Finance Without the Boilerplate

Connecting Chimoney to Claude manually means maintaining complex country schemas, polling mechanics, and raw HTTP rate-limit handling on your own infrastructure. Using Truto's dynamic MCP server architecture allows you to abstract away the REST boilerplate and focus entirely on prompt engineering and financial workflow logic.