Model Context Protocol (MCP)

The Atoa Model Context Protocol (MCP) server provides a set of tools that AI assistants and applications can use to interact with the Atoa payment API. Process payments, manage customers, handle refunds, access bank feeds, and more — all through natural language or programmatic tool calls.

HTTP Mode (hosted)

Connect any MCP-compatible client to Atoa’s hosted server. No local installation required.

NPX Mode (local)

Run the MCP server locally via npx. Works offline and keeps credentials off HTTP.

Prerequisites

Before you begin, make sure you have:

An Atoa SDK Token — follow the Getting Started guide to generate one

HTTP Mode (Recommended)

Connect any MCP-compatible client directly to Atoa’s hosted MCP server — no local installation required.

Endpoint: https://mcp.atoa.me/mcp

Pass your SDK token and target environment as request headers on every connection:

Header	Required	Value
`Authorization`	Yes	`Bearer YOUR_AUTH_TOKEN`
`X-Atoa-Env`	Yes	`sandbox` or `production`
`X-Atoa-Payment-Redirect-Url`	No	URL the customer returns to after completing payment
`X-Atoa-Ais-Redirect-Url`	No	URL the user returns to after bank authorization

Use your Sandbox token with X-Atoa-Env: sandbox and your Production token with X-Atoa-Env: production. Mixing a token with the wrong environment will return authentication errors.

AI Assistant Configuration

Most AI clients support HTTP-mode MCP connections natively. Use these configs to point your assistant directly at the Atoa MCP server.

Claude Code
Cursor
VS Code

Run from your terminal:

claude mcp add --transport http atoa https://mcp.atoa.me/mcp --header "Authorization: Bearer YOUR_AUTH_TOKEN" --header "X-Atoa-Env: sandbox"

Switch X-Atoa-Env from sandbox to production (and swap your token) when you go live.

Connecting Programmatically (MCP SDK)

For web applications and backend services, use the MCP SDK’s StreamableHTTPClientTransport:

npm install @modelcontextprotocol/sdk

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.atoa.me/mcp"),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer YOUR_AUTH_TOKEN`,
        "X-Atoa-Env": "sandbox", // or "production"
      },
    },
  },
);

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

// List available tools
const { tools } = await client.listTools();

// Execute a tool
const result = await client.callTool({
  name: "get_stores",
  arguments: {},
});

Rate Limits

The HTTP endpoint enforces rate limiting on a per-token basis. Requests that exceed the allowed rate will receive a 429 Too Many Requests response. If this happens, back off and retry after a short delay using an exponential backoff strategy.

NPX Mode (Local)

Run the Atoa MCP server locally via npx. Use this when you prefer not to send auth headers over HTTP, need to work offline, or your AI client does not support HTTP-mode MCP connections.

Requires Node.js 18+ and npm 9+ (node --version to check).

Quick Setup

The fastest way to get started is the interactive wizard:

npx @atoapayments/mcp init

This walks you through a series of prompts and generates the configuration snippet you need to add to your AI client’s config file.

Manual Configuration

Add the following to your AI client’s MCP configuration file:

Claude Desktop
Cursor
VS Code
Gemini CLI

Edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "atoa": {
      "command": "npx",
      "args": ["-y", "@atoapayments/mcp"],
      "env": {
        "ATOA_AUTH_TOKEN": "YOUR_AUTH_TOKEN",
        "ATOA_ENV": "sandbox"
      }
    }
  }
}

Claude Desktop showing an Atoa tool call result

Passing credentials via the env object keeps your token out of the process argument list, which is more secure than using --auth-token CLI flags.

Optional environment variables you can add to the env block:

Variable	Description
`ATOA_PAYMENT_REDIRECT_URL`	URL the customer returns to after completing payment
`ATOA_AIS_REDIRECT_URL`	URL the user returns to after bank authorization

Switch ATOA_ENV from sandbox to production (and swap your token) when you go live.

Once configured, restart your AI client and ask:

"Show me my Atoa stores"

If everything is set up correctly, the assistant will call get_stores and return your store list.

Available Tools

Browse the 29 tools below, organized into 8 categories. Click any category to expand.

Some tools are guarded by your merchant’s capabilities. For example, card-on-file tools require card payments to be enabled, AIS tools require AIS bank feed access, and tipping requires tipping to be enabled. Contact hello@paywithatoa.co.uk to check which features are active on your account.

Core Workflows

The simplest flow — create a payment link and check when it’s completed.

"Create a payment of £25 for order #12345"

The assistant will:

Call get_stores to resolve your default store
Call process_payment with amount: 25, currency: "GBP"
Return a paymentLink and qrCodeUrl you share with the customer
The customer opens the link or scans the QR code to pay via their bank app

amount must be a positive number with no more than 2 decimal places (e.g., 25.99 ✅ — 25.999 ❌). Currency defaults to "GBP".

Poll for completion:

"What's the status of payment abc-123-def?"

The assistant calls get_payment_status and returns one of:

Status	Meaning
`PENDING`	Awaiting customer action
`AUTHORIZED`	Card pre-authorization held (card payments only)
`COMPLETED`	Payment settled — eligible for refund
`FAILED`	Payment attempt failed
`EXPIRED`	Customer didn’t act in time (default: 30 min)
`CANCELLED`	Payment was cancelled

This two-step flow saves a card during a regular payment, then charges it in future without the customer re-entering details.

Step 1 — First payment (saves the card)

"Create a £10 payment for customer cust_abc123, and save their card"

The assistant calls process_payment with savePaymentMethod: true and atoaCustomerId: "cust_abc123". After the customer completes the payment, their card is stored.

atoaCustomerId is required when savePaymentMethod is true. The customer must exist first — create them with create_customer if needed.

Step 2 — List saved cards

"List the saved cards for customer cust_abc123"

The assistant calls list_payment_methods and returns the saved cards with masked numbers.

Step 3 — Charge the saved card

"Charge £50 to card pm_xyz for customer cust_abc123, auto-settle it"

The assistant calls charge_saved_card with:

Parameter	Value	Meaning
`captureType`	`AUTO_CAPTURE`	Charge settles immediately
`captureType`	`MANUAL_CAPTURE`	Charge is held — you must call `capture_payment` to settle
`captureType`	`CAPTURE_BEFORE_EXPIRY`	Held authorization auto-settles before it expires

charge_saved_card always returns status AUTHORIZED, not COMPLETED. For AUTO_CAPTURE, settlement happens automatically. For MANUAL_CAPTURE, you must call capture_payment to collect the funds — otherwise the authorization expires and no money moves.

Step 4 — Capture (MANUAL_CAPTURE only)

"Capture payment pay_123"

The assistant calls capture_payment with the paymentRequestId from step 3.

"Refund £15 from payment pay_abc-123"

The assistant calls initiate_refund. Key constraints:

Payment must be in COMPLETED status — pending, expired, or cancelled payments cannot be refunded
Partial refunds are supported — amount must be ≤ the original payment amount
The refund goes through as INITIATED → PENDING → COMPLETED (or FAILED)
To cancel an INITIATED refund before it processes, use cancel_refund — production only

Sandbox: To simulate a failed refund, call initiate_refund with refundNotes: "FAILURE TEST". Use this to test your error-handling paths — cancel_refund is not available in sandbox.

Webhooks notify your server when payment or refund statuses change.

"Register a webhook at https://mysite.com/webhooks/atoa for payment status updates, secured with basic auth username=atoa password=secret"

The assistant calls create_webhook with:

Field	Description
`url`	Your HTTPS endpoint
`event`	`PAYMENTS_STATUS`, `EXPIRED_STATUS`, or `REFUND_STATUS`
`authentication`	Optional — OAuth 2.0 (`clientId`, `clientSecret`, `authUrl`) or Basic Auth (`username`, `password`) — not both

You can create one webhook per event type. Register separate webhooks for payment status and refund status if you need both.

Troubleshooting

Need Help?

Contact our team at hello@paywithatoa.co.uk or use chat support on the Dashboard.

Overview

Payments

SDKs

Integration

Bank Feed

AI Solutions

HTTP Mode (hosted)

NPX Mode (local)

​Prerequisites

​HTTP Mode (Recommended)

​AI Assistant Configuration

Claude Code

Cursor

VS Code

​Connecting Programmatically (MCP SDK)

​Rate Limits

​NPX Mode (Local)

​Quick Setup

​Manual Configuration

Claude Desktop

Cursor

VS Code

Gemini CLI

​Available Tools

get_stores

process_payment

cancel_payment

get_payment_status

get_transactions

create_customer

list_customers

get_customer

update_customer

delete_customer

list_payment_methods

get_payment_method

delete_payment_method

charge_saved_card

capture_payment

cancel_card_payment

get_refund_payments

initiate_refund

cancel_refund

list_merchant_webhooks

create_webhook

delete_webhook

initiate_ais_auth

fetch_all_accounts

fetch_account_details

fetch_account_balance

fetch_account_transactions

revoke_account_access

get_institutions

​Core Workflows

​Troubleshooting

​Need Help?