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"

Edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "atoa": {
      "type": "http",
      "url": "https://mcp.atoa.me/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN",
        "X-Atoa-Env": "sandbox"
      }
    }
  }
}

Edit .vscode/mcp.json in your project root:

{
  "servers": {
    "atoa": {
      "type": "http",
      "url": "https://mcp.atoa.me/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN",
        "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

Edit .cursor/mcp.json in your project root:

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

Edit .vscode/mcp.json in your project root:

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

Edit ~/.gemini/settings.json:

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

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.

Payments (5 tools)

get_stores

List all active stores linked to your merchant account

process_payment

Create a new payment request (returns a payment link and QR code)

cancel_payment

Cancel a pending payment request

get_payment_status

Check the current status of a payment

get_transactions

Retrieve transaction history with filters (date range, status, customer)

Customers (5 tools)

create_customer

list_customers

List all customers with pagination

get_customer

Get details for a specific customer

update_customer

Update customer information

delete_customer

Remove a customer record

Payment Methods (3 tools)

list_payment_methods

List saved payment methods (cards) for a customer

get_payment_method

Get details of a specific saved card

delete_payment_method

Remove a saved card

Card on File (3 tools)

charge_saved_card

Charge a previously saved card — returns AUTHORIZED, not COMPLETED

capture_payment

Settle a pre-authorized payment (required for MANUAL_CAPTURE)

cancel_card_payment

Void a pre-authorization or unsettled card payment

Refunds (3 tools)

get_refund_payments

List refunds for a given payment

initiate_refund

Start a refund for a COMPLETED payment (full or partial)

cancel_refund

Cancel an INITIATED refund — production only

Webhooks (3 tools)

list_merchant_webhooks

List all registered webhook endpoints

create_webhook

delete_webhook

Remove a webhook endpoint

Bank Feeds (6 tools)

initiate_ais_auth

Start the bank authorization flow — returns a URL the user must visit

fetch_all_accounts

List authorized bank accounts (requires completed authorization)

fetch_account_details

Get sort code, account number and bank name for an account

fetch_account_balance

Get the current balance for an account

fetch_account_transactions

Retrieve paginated transactions for an account

revoke_account_access

Revoke access to one account, multiple accounts, or an entire session

Institutions (1 tool)

get_institutions

List all supported banking institutions

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 [email protected] to check which features are active on your account.

Core Workflows

Create a Payment

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

Save a Customer's Card and Charge It Later

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 a Payment

"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

'Merchant not found' or 401 error

Your auth token is invalid, expired, or mis-formatted. Check:

Get a fresh token from the Atoa Dashboard
HTTP mode: confirm the Authorization header is Bearer YOUR_TOKEN (with a space after Bearer) and the X-Atoa-Env header matches your token type (sandbox or production)
NPX mode: confirm ATOA_AUTH_TOKEN and ATOA_ENV are set correctly in the env block of your config
Sandbox tokens and production tokens are not interchangeable — ensure you are using the right one for each environment

Tools not appearing in my AI assistant

Restart your AI client after updating the config file — most clients load MCP config only on startup
Verify the config file path and key name match your client (see the config tabs above)
NPX mode: check Node.js version — node --version must be 18+
NPX mode: run the server manually to see errors: npx @atoapayments/mcp

charge_saved_card returns AUTHORIZED — when does it complete?

This is normal. All card payments return AUTHORIZED first.

AUTO_CAPTURE: settlement happens automatically within minutes — no action needed
MANUAL_CAPTURE: you must call capture_payment to settle the funds
CAPTURE_BEFORE_EXPIRY: Atoa auto-captures before the hold expires — no action needed unless you want early settlement

If you want immediate settlement with no extra step, use captureType: "AUTO_CAPTURE".

fetch_all_accounts returns empty or errors after initiate_ais_auth

The user must complete the bank authorization before this tool works. After calling initiate_ais_auth:

Share the authorizationUrl with the user
Wait for them to approve access in their banking app
Only then call fetch_all_accounts with the returned accountAuthId

In sandbox, the authorization URL may redirect immediately with mock data.

initiate_refund fails with 'payment not eligible'

Refunds require the payment to be in COMPLETED status. Check the payment status first with get_payment_status. You cannot refund a PENDING, EXPIRED, CANCELLED, or FAILED payment.

'cancel_refund' fails in sandbox

This is expected — cancel_refund only works in production. To test refund cancellation paths in sandbox, call initiate_refund with refundNotes: "FAILURE TEST" to simulate a failure instead.

Tool returns 403 'capability not enabled'

Some tools require specific features to be enabled on your merchant account. For example:

Card-on-file tools (charge_saved_card, capture_payment, cancel_card_payment) require card payments
AIS / Bank Feed tools require AIS bank feed access
Tips on process_payment require tipping to be enabled

Contact [email protected] to check which capabilities are active or to enable additional features.

Store not found

The get_stores tool only returns active stores. If a store is disabled in your Atoa Dashboard, it won’t appear. Enable the store in the dashboard and retry.

Connection timeout or unreachable

If you experience timeouts connecting to https://mcp.atoa.me:

Check your internet connection
Verify no firewall rules are blocking outbound HTTPS (port 443)
Check Atoa Status for service incidents

Too many requests (429)

The HTTP endpoint enforces rate limiting per token. If you receive a 429 response:

Wait briefly before retrying the request
Space out sequential tool calls
If you consistently hit rate limits for a production use case, contact [email protected]

Need Help?

Contact our team at [email protected] or use chat support on the Dashboard.

HTTP Mode (hosted)

NPX Mode (local)

​Prerequisites

​HTTP Mode (Recommended)

​AI Assistant Configuration

​Connecting Programmatically (MCP SDK)

​Rate Limits

​NPX Mode (Local)

​Quick Setup

​Manual Configuration

​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?

Prerequisites

HTTP Mode (Recommended)

AI Assistant Configuration

Connecting Programmatically (MCP SDK)

Rate Limits

NPX Mode (Local)

Quick Setup

Manual Configuration

Available Tools

Core Workflows

Troubleshooting

Need Help?