Connect Mercury to Claude: Control Cards and AR Invoices

If you need to connect Mercury to Claude to automate corporate card controls, issue Accounts Receivable (AR) invoices, or orchestrate internal treasury transfers, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Mercury'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 Mercury to ChatGPT or explore our broader architectural overview on connecting Mercury to AI Agents.

Giving a Large Language Model (LLM) read and write access to a production banking ecosystem like Mercury is an engineering challenge with high stakes. You have to handle API token lifecycles, map massive JSON schemas for financial transactions to MCP tool definitions, and deal with strict idempotency requirements to avoid accidental double-charges. Every time you want to expose a new financial operation, 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 Mercury, connect it natively to Claude, and execute complex financial workflows using natural language.

The Engineering Reality of the Mercury API

A custom MCP server is a self-hosted integration layer that translates JSON-RPC requests from an LLM into standard HTTP requests against a vendor's API. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against a banking API like Mercury is complex.

If you decide to build a custom MCP server for Mercury, you own the entire API lifecycle and the associated risk. Here are the specific challenges you will face when exposing Mercury to AI agents:

Mandatory Idempotency Keys When dealing with money movement, network timeouts are dangerous. If an LLM calls an endpoint to transfer funds, hits a timeout, and blindly retries the request, you risk moving the money twice. Mercury mandates the use of an idempotencyKey for endpoints like internal transfers and send money requests. If you write a custom MCP server, you must ensure your LLM understands how to generate and persist these keys across retry attempts. Truto dynamically maps Mercury's OpenAPI schema directly into the MCP tool definition, forcing the LLM to recognize the idempotencyKey as a required parameter before the API call is even attempted.

Complex Nested Schemas for Invoicing Creating an Accounts Receivable invoice in Mercury is not a simple flat JSON payload. The API requires a highly structured object containing nested lineItems, specific payment boolean flags (achDebitEnabled, creditCardEnabled), strict RFC3339 timestamps for dueDate, and cross-referenced customerId strings. LLMs struggle to generate these from scratch if the schema context is vague. A managed MCP server derives the exact query and body schemas from curated documentation, ensuring Claude receives precise instructions on data types and required fields, dramatically reducing schema hallucinations.

Strict Rate Limiting and 429 Passthrough Financial APIs enforce aggressive rate limits to protect infrastructure and prevent fraud. When your AI agent attempts to rapidly pull thousands of transaction records across multiple accounts, it will hit Mercury's limits.

It is a critical architectural fact that Truto does not retry, throttle, or apply backoff on rate limit errors. When Mercury returns an HTTP 429 Too Many Requests error, Truto immediately passes that error back to the caller. However, Truto normalizes the upstream rate limit information into standardized HTTP headers per the IETF specification:

• ratelimit-limit: The maximum number of requests allowed in the current window.
• ratelimit-remaining: The number of requests left in the current window.
• ratelimit-reset: The time at which the rate limit window resets.

Because Truto passes the 429 error directly, your AI agent or orchestrator is fully responsible for reading these headers and implementing the appropriate exponential backoff and retry logic.

How to Generate a Mercury MCP Server with Truto

Truto dynamically generates MCP tools from an integration's underlying resource definitions and curated documentation. This means tools are never cached or pre-built - they are evaluated at runtime, ensuring your LLM always has the most accurate schema.

You can generate a Mercury MCP server URL via the Truto UI or programmatically via the Truto API.

Method 1: Creating the Server via the Truto UI

For teams managing integrations manually, the Truto dashboard provides a point-and-click interface to provision an MCP server scoped to a specific Mercury workspace.

1. Navigate to the Integrated Accounts page in your Truto dashboard and select the connected Mercury account.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Define your server configuration. You can filter the server to only expose specific methods (like read operations) or restrict it to specific resource tags (like invoices or cards).
5. Click Create and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...). Keep this URL secure, as it contains the cryptographic token required for access.

Method 2: Creating the Server via the Truto API

For platform engineers building multi-tenant AI products, you need to provision MCP servers dynamically when a customer connects their Mercury account. You can do this by making a POST request to the Truto API.

Endpoint: POST /integrated-account/:id/mcp

curl -X POST "https://api.truto.one/integrated-account/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/mcp" \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mercury Treasury Ops Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["cards", "invoices", "transactions"]
    }
  }'

The Truto API verifies that the underlying integration has documented tools available, generates a secure hexadecimal token, stores a hashed version in a distributed key-value store, and returns the configuration along with the connection URL.

{
  "id": "mcp_8f7e6d5c4b3a21",
  "name": "Mercury Treasury Ops Agent",
  "config": {
    "methods": ["read", "write"],
    "tags": ["cards", "invoices", "transactions"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

How to Connect the MCP Server to Claude

Once you have your Truto MCP server URL, you need to register it with your Claude environment. You can connect it via the Claude application UI or configure it manually using the Claude Desktop configuration file.

Method A: Connecting via the Claude UI

If you are using Claude for Web or the Claude Desktop interface, Anthropic provides a native UI for adding external tools.

1. Open Claude and navigate to Settings.
2. Locate the Integrations or Connectors section.
3. Click Add MCP Server or Add custom connector.
4. Paste the Truto MCP server URL you copied earlier.
5. Click Add.

Claude will immediately perform a JSON-RPC handshake (initialize and tools/list) with the Truto endpoint. Truto dynamically builds the tool definitions based on the Mercury integration and returns them to Claude. No additional authentication configuration is needed unless you explicitly enabled API token requirements during server creation.

Method B: Connecting via Manual Configuration File

For advanced developers using Claude Desktop who want strict version control over their agent environments, you can manually inject the MCP server URL into the configuration file.

Open your claude_desktop_config.json file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add the server configuration using the SSE (Server-Sent Events) transport command:

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

Restart Claude Desktop. The client will connect to the Truto SSE endpoint and populate the agent's context window with the available Mercury tools.

Mercury Hero Tools for AI Agents

Truto automatically translates Mercury's API endpoints into snake_case tool names that Claude can easily interpret. Below are the most critical operations for automating treasury, card management, and accounts receivable tasks.

list_all_mercury_card

This tool retrieves a list of all active, frozen, or canceled virtual and physical cards across the organization. It supports filtering by user ID or card status, making it ideal for auditing corporate spend capacity.

Contextual Usage: Use this when a user asks to review card limits or needs to find a specific card ID before attempting to freeze or modify it.

"Claude, pull a list of all active virtual cards assigned to the marketing department and summarize their current spend limits."

update_a_mercury_card_by_id

This tool modifies the metadata or spending controls on an existing Mercury card. It requires the card id and allows you to update the nickname or adjust the spendLimit to tightly control unauthorized expenses.

Contextual Usage: Essential for automated budget enforcement. If an agent detects anomalous spending or receives a request to increase a contractor's budget, it can update the limit directly.

"Find the virtual card ending in 4092 and decrease its spending limit to $500 effective immediately."

create_a_mercury_customer

Before you can issue an Accounts Receivable invoice, Mercury requires a customer record to exist. This tool generates that record, requiring only a name and email.

Contextual Usage: Always call this tool first if you are generating an invoice for a brand-new client. Capture the returned id to use in subsequent invoice creation steps.

"Create a new AR customer profile for Acme Corporation using the billing email finance@acmecorp.com."

create_a_mercury_invoice

This tool generates a formal Accounts Receivable invoice. It requires a complex payload including lineItems, the customerId, strict datetime strings for the dueDate, and boolean flags for accepted payment methods like achDebitEnabled.

Contextual Usage: Because of the complex schema, ensure your prompt provides all necessary line item details (description, quantity, unit price). Claude will use the schema provided by Truto to format the JSON perfectly.

"Generate an invoice for the customer ID we just created. The total is $10,000 for 'Q4 Software Implementation', due in 30 days. Enable ACH payments only."

create_a_mercury_internal_transfer

This tool moves funds between two internal Mercury accounts within the same organization. It requires a sourceAccountId, destinationAccountId, amount, and crucially, an idempotencyKey.

Contextual Usage: Use this for cash sweeps or funding operational accounts from a central treasury account. Instruct the model to generate a unique string (like a UUID) for the idempotency key.

"Transfer $50,000 from the main Treasury account to the Payroll funding account. Make sure to generate a unique idempotency key for this transaction."

list_all_mercury_transaction

This tool pulls a ledger of all transactions across Mercury accounts. It returns detailed records including the amount, status, counterparty data, and attached metadata.

Contextual Usage: Use this tool for reconciliation, fraud detection, or generating automated daily cash flow summaries.

"Fetch the last 50 transactions across all our accounts and flag any outbound wire transfers over $10,000 that occurred this week."

To view the complete inventory of available tools and their underlying JSON schemas, check out the Mercury integration page.

Workflows in Action

Once connected, Claude can string these tools together to execute multi-step operations—a common pattern in complex AI agent tool calling workflows—that would normally require a human to log into the Mercury dashboard.

Scenario 1: Automated Spend Control

An IT administrator wants to quickly lock down a contractor's spending capacity without navigating the Mercury UI.

"Find the virtual card assigned to 'Jane Doe' and reduce her spend limit to $250. Once that is done, pull her transaction history for the last 7 days."

Execution Steps:

1. Claude calls list_all_mercury_card passing a filter or searching the output for "Jane Doe" to locate the specific card id.
2. Claude extracts the id and calls update_a_mercury_card_by_id, passing {"id": "card_abc123", "spendLimit": 250}.
3. Claude calls list_all_mercury_transaction, filtering the results to match transactions associated with Jane's account or card over the last week.
4. The agent returns a summary confirming the new limit is active and provides a bulleted list of the recent transactions.

sequenceDiagram
    participant Admin as IT Admin
    participant Claude as Claude Desktop
    participant Truto as Truto MCP Server
    participant Mercury as Mercury API

    Admin->>Claude: "Reduce Jane's card limit to $250..."
    Claude->>Truto: Call list_all_mercury_card
    Truto->>Mercury: GET /cards
    Mercury-->>Truto: Return card array
    Truto-->>Claude: JSON response
    Claude->>Truto: Call update_a_mercury_card_by_id (id, spendLimit: 250)
    Truto->>Mercury: PATCH /cards/{id}
    Mercury-->>Truto: Success
    Truto-->>Claude: JSON response
    Claude->>Admin: "Card limit updated to $250."

Scenario 2: Frictionless Accounts Receivable

A sales operations manager needs to quickly bill a new client based on a signed contract.

"We just closed a deal with Globex. Create a new customer profile for billing@globex.com. Then, issue them an invoice for $15,000 for an 'Annual Enterprise License' due on November 1st. Allow both credit card and ACH payments."

Execution Steps:

1. Claude calls create_a_mercury_customer, passing {"name": "Globex", "email": "billing@globex.com"}.
2. Truto returns the new customer object containing the id (e.g., cust_999).
3. Claude parses the required date (November 1st) into RFC3339 format based on the schema instructions.
4. Claude calls create_a_mercury_invoice, injecting cust_999 into the payload, formatting the $15,000 line item, and setting achDebitEnabled: true and creditCardEnabled: true.
5. The agent returns the invoice ID and dashboard link, confirming the bill has been generated.

Security and Access Control

Giving an AI agent access to banking infrastructure requires strict boundaries. Truto provides four distinct mechanisms to secure your Mercury MCP server:

• Method Filtering: You can restrict a server to safe operations by configuring methods: ["read"]. This allows the LLM to call list and get endpoints for auditing, but prevents it from executing create, update, or delete methods.
• Tag Filtering: By passing tags: ["invoices"], the MCP server will only generate tools related to accounts receivable, hiding sensitive resources like internal transfers or user directories from the agent.
• Secondary API Authentication: By default, the long-lived MCP URL acts as a bearer token. For enterprise deployments, setting require_api_token_auth: true forces the client to also pass a valid Truto API token in the headers, adding an identity verification layer.
• Automatic Expiration: You can provision temporary access for an external consultant or auditor by setting an expires_at timestamp. Once the timestamp passes, the token is automatically deleted from the edge store and all access is revoked.

Summary

Building a custom integration layer between Claude and Mercury requires managing idempotency, strict nested schemas, and HTTP 429 rate limit backoff logic. By utilizing a managed MCP server via Truto, you offload the authentication handling and dynamic tool generation, allowing your AI agents to reliably control virtual cards, issue invoices, and query ledgers using natural language.