Connect Airwallex to Claude: Manage Subscriptions and Spend Records

If your team needs to connect Airwallex to Claude to automate cross-border payouts, manage recurring subscriptions, or reconcile complex spend records, you need a Model Context Protocol (MCP) server. This server acts as the critical translation layer between Claude's natural language tool calls and Airwallex'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 Airwallex to ChatGPT or explore our broader architectural overview on connecting Airwallex to AI Agents.

Giving a Large Language Model (LLM) read and write access to a sprawling financial ecosystem like Airwallex is an engineering challenge. You have to handle API token lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Airwallex's strict financial data validation rules. Every time Airwallex updates an endpoint or deprecates a legacy payment intent model, 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 Airwallex, connect it natively to Claude Desktop, and execute complex financial workflows using natural language.

The Engineering Reality of the Airwallex API

A custom MCP server is essentially a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Airwallex's API is painful. You are not just integrating "Airwallex" - you are integrating their Core API (deposits, transfers, FX), their Issuing API (cards), their Spend API (AP/AR and expenses), and their Payment Acceptance API, all of which exhibit slightly different design patterns.

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

Strict Idempotency on Money Movement Airwallex enforces strict idempotency on almost all non-read operations. Endpoints like creating a transfer, booking an FX conversion, or generating a payout require a highly unique request_id. If an LLM retries a failed prompt without regenerating a unique UUID for the request_id, Airwallex will reject the payload or return the cached response of the previous attempt. Your MCP server must either wrap these endpoints to auto-inject idempotency keys or explicitly train the LLM to generate them per call.

Mutually Exclusive FX Parameters When booking an FX quote or conversion, Airwallex requires precise payload structures that LLMs often hallucinate. For example, when calling the conversion endpoint, you must supply a buy_currency and a sell_currency, but you can only supply exactly one of buy_amount or sell_amount (the dealt side). If Claude attempts to send both amounts, the Airwallex API throws a 400 Bad Request. Creating effective MCP tools requires modifying the underlying API schema descriptions to explicitly warn the LLM about these mutually exclusive fields.

Handling Rate Limits Without Middleware Masking Airwallex enforces strict rate limits to protect financial operations. A critical architectural choice when building MCP servers is how to handle these limits. Truto takes a pass-through approach: Truto does not retry, throttle, or apply backoff on rate limit errors. When the Airwallex API returns an HTTP 429, Truto passes that error directly to the caller.

Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (in this case, the Claude client) is strictly responsible for interpreting the failure, reading the headers, and applying backoff. You should never design an MCP server to silently absorb rate limit errors, especially in financial contexts where a silent timeout could lead to duplicate payment processing.

flowchart TD
  Claude["Claude Desktop"] -->|"JSON-RPC<br>tools/call"| TrutoMCP["Truto MCP Server<br>(/mcp/:token)"]
  TrutoMCP -->|"KV Lookup<br>& Validation"| TokenCheck["Token Auth<br>& Validation"]
  TokenCheck -->|"Proxy API Request<br>w/ Credentials"| AirwallexAPI["Airwallex API<br>(REST endpoints)"]
  AirwallexAPI -->|"HTTP 429<br>(Pass-through)"| TrutoMCP
  TrutoMCP -->|"IETF Headers<br>ratelimit-remaining"| Claude

How to Create the Airwallex MCP Server

Truto bypasses the need to manually code tools by dynamically generating them. Truto reads the Airwallex resource endpoints and documentation records, parses the query and body schemas, and exposes them as an MCP-compliant JSON-RPC 2.0 endpoint.

You can generate the MCP server URL in two ways.

Method 1: Via the Truto UI

This is the fastest method for internal operational teams who want to give Claude immediate access to a specific Airwallex account.

1. Navigate to the Integrated Accounts page in your Truto dashboard.
2. Select your connected Airwallex account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., restrict to read-only methods, set an expiration date, or select specific tags).
6. Copy the generated MCP server URL.

Method 2: Via the Truto API

If you are building an application that programmatically spins up agentic workspaces for your users, you can generate MCP servers via API. This creates a secure, hashed token stored in Key-Value storage for fast authentication.

POST /integrated-account/:id/mcp

{
  "name": "Airwallex FinOps Agent",
  "config": {
    "methods": ["read", "write"],
    "tags": ["treasury", "spend"]
  },
  "expires_at": "2025-12-31T23:59:59Z"
}

The API responds with the secure MCP URL:

{
  "id": "mcp_8a9b0c",
  "name": "Airwallex FinOps Agent",
  "expires_at": "2025-12-31T23:59:59Z",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67g8h9i0"
}

How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you can connect it directly to your LLM client.

Method A: Via the Claude UI

For business users utilizing Claude's native application interfaces:

1. Open Claude Desktop or Claude Web.
2. Navigate to Settings -> Integrations.
3. Click Add MCP Server (or Add Custom Connector).
4. Paste the Truto MCP URL.
5. Click Add.

(Note: If your team utilizes ChatGPT, the process is similar: Navigate to Settings -> Apps -> Advanced settings -> Enable Developer mode -> Add Custom Connector under MCP servers).

Method B: Via Manual Config File

If you are running Claude Desktop locally and prefer configuring connections manually, you can edit your claude_desktop_config.json file. Since Truto provides a standard HTTP endpoint, you map it using the Server-Sent Events (SSE) transport adapter.

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

Once saved, restart Claude Desktop. The model will send an initialize JSON-RPC handshake, and Truto will dynamically return the available Airwallex tools.

Hero Tools for Airwallex

By leveraging Truto's dynamic tool generation, Claude instantly gains access to a vast array of Airwallex capabilities. Tool names are generated dynamically using a descriptive snake_case format (e.g., list_all_airwallex_balances).

Here are some of the highest-leverage hero tools your AI agents will use to orchestrate Airwallex.

List All Balances

This tool retrieves the current wallet balances across all enabled currencies, returning both available and pending amounts. It is essential for checking liquidity before initiating large payouts or FX conversions.

"Check our current Airwallex balances. Do we have enough available GBP to cover a £45,000 vendor payment, or do we need to convert USD first?"

Create an FX Conversion

Allows the model to execute a spot FX conversion between two currencies in your Airwallex wallet. The schema strictly enforces that the LLM provides the buy_currency, sell_currency, and only one of the amount values (the dealt side).

"Book an FX conversion to buy exactly 50,000 EUR using our USD balance. Generate a unique request ID for this transaction."

Create a Transfer

Initiates a payout to an external beneficiary. The LLM can specify the transfer amount, currency, beneficiary details, and payment rails (e.g., local clearing vs SWIFT).

"Initiate a transfer of $12,500 USD to the pre-saved beneficiary ID 'ben_8910x'. Set the reason to 'Q3 Marketing Retainer'."

Create a Billing Subscription

Sets up a recurring subscription charge for an existing Airwallex Billing Customer. The model defines the collection method, currency, and line items (prices and quantities).

"Create a new monthly subscription for customer 'cus_384ab'. Add the 'Pro Tier Software' price ID, quantity 10, starting immediately."

List Spend Bills

Queries Accounts Payable (AP) bills stored in Airwallex Spend. This is highly useful for autonomous agents that reconcile vendor invoices, checking statuses or sync states with external accounting tools.

"Retrieve all Airwallex Spend bills from the last 7 days that have a status of unpaid and summarize the vendors we owe money to."

Get Single FX Quote

Generates an indicative FX quote that locks in an exchange rate for a set validity period. Useful when an agent needs to present a cost preview to a human operator before executing a final trade.

"Generate an FX quote to sell 100,000 AUD for JPY. What is the guaranteed client rate and when does this quote expire?"

(For a complete inventory of Airwallex resources, schemas, and endpoints, visit the Airwallex integration page.)

Workflows in Action

Connecting Claude to Airwallex via MCP isn't just about reading data - it's about chaining multiple operations together to execute complex Financial Operations (FinOps).

Scenario 1: Multi-Currency Vendor Payment & FX Execution

A finance manager needs to pay a European supplier, but the primary treasury account holds USD. They want Claude to check the balance, calculate the conversion, execute the trade, and send the funds.

"We need to pay vendor 'ben_euro77' exactly €25,000. Check our EUR balance. If we are short, book an FX conversion from USD to cover the exact difference, then initiate the transfer."

Step-by-step execution:

1. Claude calls list_all_airwallex_balances to check the current EUR availability. It discovers only €5,000 is available.
2. Claude realizes it needs €20,000 more. It calls create_a_airwallex_conversions_create, passing buy_currency: "EUR", sell_currency: "USD", and buy_amount: 20000.
3. Claude parses the conversion success response, noting the updated balance.
4. Claude calls create_a_airwallex_transfers_create for €25,000 to the beneficiary, generating a unique request_id to ensure idempotency.

Scenario 2: Autonomous SaaS Onboarding and Billing

A sales operations agent wants to onboard a new customer and immediately issue the first invoice for a bespoke implementation fee, followed by a recurring subscription.

"Set up a new billing customer for Acme Corp (billing@acme.test). Create a one-off invoice for $5,000 USD for 'Implementation Fees' and finalize it. Then, set up their recurring monthly software subscription."

Step-by-step execution:

1. Claude calls create_a_airwallex_billing_customer with the provided business details and email.
2. Using the returned customer_id, Claude calls create_a_airwallex_billing_invoice, attaching a single line item for the $5,000 fee.
3. Claude calls airwallex_billing_invoices_finalize to lock the draft invoice and make it payable.
4. Finally, Claude calls create_a_airwallex_billing_subscription using the customer_id and the pre-existing product price IDs to start the recurring billing cycle.

sequenceDiagram
  participant Claude as Claude Desktop
  participant MCP as Truto MCP Router
  participant Airwallex as Airwallex API
  Claude->>MCP: tools/call: create_a_airwallex_billing_customer
  MCP->>Airwallex: POST /api/v1/pa/billing/customers
  Airwallex-->>MCP: Returns customer_id
  MCP-->>Claude: JSON-RPC Result
  Claude->>MCP: tools/call: create_a_airwallex_billing_invoice
  Note over Claude: Uses customer_id<br>from previous step
  MCP->>Airwallex: POST /api/v1/pa/billing/invoices
  Airwallex-->>Claude: Invoice Created

Security and Access Control

Exposing financial infrastructure to AI models demands zero-trust architecture. Truto MCP servers are heavily sandboxed and strictly scoped to individual integrated accounts. You maintain complete control over what the model can execute.

• Method Filtering: Limit Claude's capabilities at the API level. By passing config.methods: ["read"] during server creation, you ensure the AI can only execute safe GET and LIST operations (e.g., checking balances), explicitly blocking write endpoints like FX conversions.
• Tag Filtering: Group API capabilities logically. If you only want the LLM to access the Airwallex Spend features, you can pass config.tags: ["spend"]. Truto will filter out the Issuing or Global Accounts endpoints entirely.
• Required API Authentication: By default, possessing the cryptographically hashed MCP URL is enough to access the tools. For higher security, setting require_api_token_auth: true forces Claude to also pass a valid Truto API token in the headers, adding a secondary layer of authentication.
• Automated Expiry (expires_at): You can grant temporal access. If you only need an agent to perform an end-of-month reconciliation, set expires_at to Friday at 5 PM. A durable object schedules an alarm that automatically destroys the Key-Value storage token and database record precisely on time.

Rethinking Financial Integrations

Integrating AI with platforms like Airwallex shouldn't require building massive stateful middle-tiers just to parse financial JSON schemas. By utilizing a managed MCP server, you eliminate the integration debt of OAuth flows, idempotency wrapping, and constant API deprecation monitoring.

With Truto handling the protocol translation, rate limit normalization, and dynamic tool generation, your engineering team can focus on designing robust AI prompts and sophisticated FinOps logic - leaving the plumbing to the infrastructure layer.