Connect Adyen to Claude: Automate Refunds, Links, and Dispute Flows

If you need to connect Adyen to Claude to automate customer refunds, generate payment links, or manage complex chargeback dispute flows, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Adyen's strict REST APIs. 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 /connect-adyen-to-chatgpt-manage-payments-accounts-and-terminals/ or explore our broader architectural overview on /connect-adyen-to-ai-agents-handle-onboarding-balances-and-transfers/.

Giving a Large Language Model (LLM) read and write access to a sprawling financial ecosystem like Adyen is an engineering challenge. You have to handle API key lifecycles, map massive JSON schemas to MCP tool definitions, and deal with Adyen's strict idempotency requirements and asynchronous webhooks. Every time Adyen updates an endpoint or migrates a legacy API to the new Checkout API, 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 Adyen, connect it natively to Claude Desktop, and execute complex payment and dispute workflows using natural language.

The Engineering Reality of the Adyen 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, the reality of implementing it against Adyen's APIs is painful. You are not just integrating a simple database - you are interacting with a highly regulated, asynchronous financial ledger.

If you decide to build a custom MCP server for Adyen, here are the specific integration challenges you will face:

Asynchronous Webhook-Driven State Validation Adyen is designed around asynchronous state changes. When you issue a refund or a capture request via the API, the HTTP response simply acknowledges the receipt of the request ([pspReference]). The actual success or failure of that financial movement is delivered minutes or hours later via an asynchronous webhook (e.g., REFUND_FAILED or AUTHORISATION_ADJUSTMENT). An LLM has no concept of this delay. If you build a naive MCP server, Claude will assume a 200 OK means the money has successfully moved. You must design your tools to explicitly inform the LLM that the returned reference ID must be tracked later, or build a polling mechanism into your custom server logic.

Fragmented API Domains and Legacy Endpoints Adyen's API surface area is massive and historically fragmented. While they are actively pushing merchants to the unified Checkout API and Transfers API, many specific actions still require hitting legacy endpoints or specific domain services (like the Balance Platform API, Management API, or BinLookup API). An LLM does not know which endpoint to use for which merchant setup. Your MCP server must abstract these routing complexities, presenting unified, goal-oriented tools to the agent rather than raw REST methods.

Strict Idempotency and Nested Schemas Financial APIs enforce strict idempotency to prevent double-charging. Adyen requires carefully managed idempotency keys for modifications (refunds, captures, cancels). Furthermore, Adyen's JSON schemas are deeply nested - requiring exact combinations of merchantAccount, pspReference, and specific amount objects containing both value (in minor units) and currency. If an LLM hallucinates the minor unit conversion (e.g., sending 100 instead of 10000 for $100.00), the financial impact is immediate. You must enforce strict JSON Schema definitions in your tool generation.

Generating a Managed MCP Server for Adyen

Instead of building a Node.js or Python server from scratch, writing routing logic, and hand-coding Adyen's schemas into MCP tool definitions, you can use Truto.

Truto automatically generates MCP tools dynamically. It derives these tools from Adyen's integration definitions and curated documentation records. If an endpoint is documented in Truto's registry, it becomes a strongly typed MCP tool automatically. The server runs at the edge, authenticates requests via a secure token, and delegates execution to Truto's proxy infrastructure.

You can generate an Adyen MCP server in two ways: via the Truto UI, or programmatically via the API.

Method 1: Via the Truto UI

For internal teams or ad-hoc workflows, you can spin up an MCP server directly from the dashboard:

1. Navigate to your Integrated Accounts in the Truto dashboard.
2. Select your connected Adyen account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., filter to only read methods, or tag filters like payments).
6. Copy the generated MCP Server URL (e.g., https://api.truto.one/mcp/a1b2c3d4...).

Method 2: Via the Truto REST API

For platforms provisioning AI agents for end-users, you can generate MCP servers programmatically. Submit a POST request to the /mcp endpoint for the specific integrated account.

curl -X POST https://api.truto.one/integrated-account/{account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Adyen Dispute Resolution Agent",
    "config": {
      "methods": ["read", "write"],
      "tags": ["payments", "disputes"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The API provisions a distributed key-value entry for authentication, hashes the token, and returns a ready-to-use URL:

{
  "id": "mcp_srv_987654",
  "name": "Adyen Dispute Resolution Agent",
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the Adyen MCP Server to Claude

Once you have your Truto MCP URL, connecting it to Claude requires zero additional coding. The token in the URL handles all authentication and context scoping to the specific Adyen tenant.

Method 1: Via the Claude UI (Claude Desktop or ChatGPT)

If you are using Claude Desktop (or ChatGPT's custom connectors feature), you can drop the URL directly into the interface:

1. Open Claude Desktop.
2. Navigate to Settings -> Integrations -> Add MCP Server (For ChatGPT: Settings -> Apps -> Advanced settings -> Add custom connector).
3. Enter a name (e.g., "Adyen Production").
4. Paste the Truto MCP Server URL.
5. Click Add or Save.

Claude will immediately initiate the MCP handshake, request tools/list, and populate its context with the available Adyen tools.

Method 2: Via Manual Configuration File

If you prefer configuring Claude Desktop manually via its JSON configuration file, or if you are running a headless agent framework, you can use the official @modelcontextprotocol/server-sse package to proxy the connection.

Edit your claude_desktop_config.json (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Restart Claude Desktop. The application will execute the command and tunnel the SSE stream into standard JSON-RPC 2.0 messages.

Adyen Hero Tools for Claude

Truto exposes the entirety of the Adyen REST API as MCP tools. The schemas are automatically enhanced - for instance, list endpoints receive limit and next_cursor injection, while path parameters are extracted into the flat JSON-RPC argument namespace.

Here are the highest-leverage tools for automating Adyen operations with Claude.

create_a_adyen_payment_link

Generates an Adyen Pay By Link URL. This tool allows the AI to dynamically generate secure checkout pages for invoice recovery, support upsells, or custom B2B orders. It requires the amount and merchant account context.

"Generate a payment link for $500.00 USD under our US_Merchant_Account. Set the reference to INV-2025-044 and set it to expire in 24 hours. Give me the short URL."

create_a_adyen_payment_refund

Initiates a partial or full refund against a captured Adyen payment using the payment's PSP reference. Because the original charge might be settled, this tool delegates to the Checkout API's refunds endpoint.

"The customer for order #9988 wants to return one item. Find the original payment PSP reference, and issue a partial refund of 25.00 EUR from the EU_Merchant_Account."

create_a_adyen_dispute

Raises an Adyen dispute for an underlying transaction. This is critical for orchestrating chargeback responses or managing fraud flows programmatically.

"Create a new dispute for transaction PSP-994829. Mark the dispute type as 'Not Delivered' and set the disputed amount to 150.00 USD."

adyen_disputes_attach_attachment

Adds supporting evidence (receipts, communication logs, shipping tracking) to a raised Adyen dispute. The tool accepts Base64-encoded file content.

"Take the shipping confirmation PDF for order #5512, encode it in Base64, and attach it to the dispute ID 88711 as a 'ShippingProof' document."

create_a_adyen_payment_cancel

Cancels an authorization on a payment that has not yet been captured. This is used to release holds on customer cards immediately if an order is flagged for fraud or canceled before fulfillment.

"The compliance system flagged PSP-112233 as high risk. Cancel the authorization immediately on the US_Merchant_Account so the customer's funds are released."

create_a_adyen_transfer

Creates a funds transfer in Adyen via the Transfers API. This is used for pushing payouts to third-party bank accounts, funding balance accounts, or orchestrating marketplace splits.

"Initiate a transfer of 1,200.00 GBP to the counterparty account ID CPT-8812. Tag the category as 'payout' and provide the transfer status once accepted."

For the complete inventory of available Adyen tools, query schemas, and return types, visit the Adyen Integration Page.

Workflows in Action

Exposing individual endpoints to an LLM is useful, but the true power of MCP comes from chaining these tools together to execute complex, multi-step domain workflows.

1. Automated Dispute Defense & Evidence Submission

Managing chargebacks manually is a massive resource drain for merchants. An AI agent can automatically retrieve transaction data, locate the corresponding shipping evidence in your internal systems, and submit a complete defense package to Adyen.

"We just received a chargeback notification for transaction PSP-554433. Find the transaction details, look up the shipping tracking number in our internal logistics API, create a dispute defense in Adyen for 'Services Rendered', and attach the tracking text as evidence."

Execution Steps:

1. get_single_adyen_transaction_by_id: The agent retrieves the transaction details from Adyen using the PSP reference to confirm the amount and status.
2. internal_logistics_get_order: The agent uses a custom internal tool (also connected to Claude) to fetch the shipping tracking details using the Adyen merchant reference.
3. create_a_adyen_dispute: The agent raises the dispute defense in Adyen, assigning the correct defenseReasonCode.
4. adyen_disputes_attach_attachment: The agent formats the shipping data into a document, encodes it, and attaches it to the dispute to finalize the defense.

sequenceDiagram
    participant Claude as Claude Desktop
    participant TrutoMCP as Truto MCP Server
    participant Adyen as Adyen API
    participant Internal as Internal DB

    Claude->>TrutoMCP: Call get_single_adyen_transaction_by_id
    TrutoMCP->>Adyen: GET /transactions/PSP-554433
    Adyen-->>TrutoMCP: Return transaction data
    TrutoMCP-->>Claude: JSON context
    Claude->>Internal: Call internal_logistics_get_order
    Internal-->>Claude: Return tracking data
    Claude->>TrutoMCP: Call create_a_adyen_dispute
    TrutoMCP->>Adyen: POST /disputes
    Adyen-->>TrutoMCP: Return dispute ID
    TrutoMCP-->>Claude: Return dispute ID
    Claude->>TrutoMCP: Call adyen_disputes_attach_attachment
    TrutoMCP->>Adyen: POST /disputes/{id}/attachments
    Adyen-->>TrutoMCP: Return success
    TrutoMCP-->>Claude: Return attachment confirmation

2. Support Operations: Immediate Authorization Cancellation & Refund

Customer support agents frequently need to navigate multiple systems to cancel an order and ensure the customer's money is returned. An AI agent can handle the financial routing automatically based on the transaction's capture state.

"Customer email: 'I accidentally ordered the premium tier, please cancel it immediately.' Check their latest Adyen transaction. If it's only authorized, cancel it. If it's already captured, issue a full refund."

Execution Steps:

1. get_single_adyen_transaction_by_id: The agent looks up the customer's latest transaction to check the status field.
2. Decision Logic: Claude evaluates the status. If Authorised, it proceeds to cancel. If Captured, it proceeds to refund.
3. create_a_adyen_payment_cancel: If authorized, the agent calls the cancel tool to release the hold.
4. create_a_adyen_payment_refund: If captured, the agent invokes the refund tool for the full amount.

Handling Adyen Rate Limits

When connecting AI agents to production financial systems, rate limits become a critical stability concern. An aggressive LLM loop can easily overwhelm Adyen's API quotas.

Truto approaches this with explicit transparency. Truto does not silently absorb, retry, or apply exponential backoff to rate limit errors. When Adyen rejects a request with an HTTP 429 Too Many Requests, Truto passes that 429 directly back to the calling client. Furthermore, Truto normalizes the upstream rate limit information into standardized IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset).

The caller (your agent framework or Claude) is entirely responsible for reading these headers, understanding the quota exhaustion, and implementing appropriate retry or backoff logic before invoking the tool again. This ensures your agent's reasoning loop is fully aware of its environment constraints.

Security and Access Control

Exposing an Adyen MCP server to an AI model requires strict governance. Possession of the Truto MCP URL grants access to the tools, so you must restrict what the server is capable of doing.

• Method Filtering: You can lock down an MCP server to strictly read-only operations by passing config.methods: ["read"] during creation. This ensures the LLM can only query data (e.g., list transactions, view balances) and structurally cannot execute writes (refunds, payouts).
• Tag Filtering: Adyen resources can be grouped. Passing config.tags: ["disputes"] restricts the server to only expose tools related to dispute management, preventing the agent from accidentally listing webhooks or modifying terminal settings.
• Expiration (TTL): You can generate temporary, short-lived MCP servers by setting expires_at. Once the timestamp is reached, the underlying distributed key-value store automatically purges the token, permanently revoking access.
• Require API Token Auth: By setting require_api_token_auth: true, the bare MCP URL is no longer sufficient. The connecting client must also inject a valid Truto session or API token into the Authorization header, adding a required secondary authentication layer.

Moving Forward with Agentic Payments

Connecting Adyen to Claude transforms your financial infrastructure from a static set of dashboards into an active, programmable workspace. By leveraging Truto to auto-generate the MCP server, you eliminate the overhead of tracking schema changes, maintaining infrastructure, and writing boilerplate HTTP clients. You enforce strict JSON schemas, filter capabilities at the edge, and empower your AI agents to resolve disputes, issue refunds, and generate payment links autonomously.

Stop building fragile REST wrappers for your LLMs. Let the documentation drive the tools.