> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paywithatoa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Model Context Protocol (MCP)

> Connect AI assistants to Atoa with the Model Context Protocol (MCP) server, let agents create payments, check status and manage data.

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)](#http-mode-recommended)**
>
> Connect any MCP-compatible client to Atoa's hosted server. No local installation required.

> **[NPX Mode (local)](#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](https://docs.paywithatoa.com/introduction.md#step-1-sign-up-for-developer-access) 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 |

> [!WARNING]
>
> 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**

Run from your terminal:

```bash theme={null}
claude mcp add --transport http atoa https://mcp.atoa.me/mcp --header "Authorization: Bearer YOUR_AUTH_TOKEN" --header "X-Atoa-Env: sandbox"
```

![Atoa MCP tools loaded in Claude Code](https://mintcdn.com/atoaproddocs/ZhMdcV3xf3fCdH09/images/claude-code-example-mcp.gif?s=7042eabe03ebe04c84e38645c1993c50)

**Cursor**

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

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

**VS Code**

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

```json theme={null}
{
  "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`:

```bash theme={null}
npm install @modelcontextprotocol/sdk
```

```typescript theme={null}
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:

```bash theme={null}
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**

Edit `claude_desktop_config.json`:

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

```json theme={null}
{
  "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](https://mintcdn.com/atoaproddocs/ZhMdcV3xf3fCdH09/images/claude-desktop-example-mcp.gif?s=9bd292d9388eea224173ea704f882bc8)

**Cursor**

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

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

**VS Code**

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

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

**Gemini CLI**

Edit `~/.gemini/settings.json`:

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

> [!NOTE]
>
> 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](https://docs.paywithatoa.com/api-reference/payment/get-stores.md)**
> >
> > List all active stores linked to your merchant account
>
> > **[process\_payment](https://docs.paywithatoa.com/api-reference/payment/process-payment.md)**
> >
> > Create a new payment request (returns a payment link and QR code)
>
> > **[cancel\_payment](https://docs.paywithatoa.com/api-reference/payment/cancel-payment.md)**
> >
> > Cancel a pending payment request
>
> > **[get\_payment\_status](https://docs.paywithatoa.com/api-reference/payment/get-payment-status.md)**
> >
> > Check the current status of a payment
>
> > **[get\_transactions](https://docs.paywithatoa.com/api-reference/payment/get-transactions.md)**
> >
> > Retrieve transaction history with filters (date range, status, customer)

> **Customers (5 tools)**
>
> > **[create\_customer](https://docs.paywithatoa.com/api-reference/customers/create-customer.md)**
> >
> > Register a new customer — requires either `email` or `phoneNumber`
>
> > **[list\_customers](https://docs.paywithatoa.com/api-reference/customers/list-customers.md)**
> >
> > List all customers with pagination
>
> > **[get\_customer](https://docs.paywithatoa.com/api-reference/customers/get-customer.md)**
> >
> > Get details for a specific customer
>
> > **[update\_customer](https://docs.paywithatoa.com/api-reference/customers/update-customer.md)**
> >
> > Update customer information
>
> > **[delete\_customer](https://docs.paywithatoa.com/api-reference/customers/delete-customer.md)**
> >
> > Remove a customer record

> **Payment Methods (3 tools)**
>
> > **[list\_payment\_methods](https://docs.paywithatoa.com/api-reference/payment-methods/list-payment-methods.md)**
> >
> > List saved payment methods (cards) for a customer
>
> > **[get\_payment\_method](https://docs.paywithatoa.com/api-reference/payment-methods/get-payment-method.md)**
> >
> > Get details of a specific saved card
>
> > **[delete\_payment\_method](https://docs.paywithatoa.com/api-reference/payment-methods/delete-payment-method.md)**
> >
> > Remove a saved card

> **Card on File (3 tools)**
>
> > **[charge\_saved\_card](https://docs.paywithatoa.com/api-reference/card-on-file/charge-saved-card.md)**
> >
> > Charge a previously saved card — returns `AUTHORIZED`, not `COMPLETED`
>
> > **[capture\_payment](https://docs.paywithatoa.com/api-reference/card-on-file/capture-payment.md)**
> >
> > Settle a pre-authorized payment (required for `MANUAL_CAPTURE`)
>
> > **[cancel\_card\_payment](https://docs.paywithatoa.com/api-reference/card-on-file/cancel-payment.md)**
> >
> > Void a pre-authorization or unsettled card payment

> **Refunds (3 tools)**
>
> > **[get\_refund\_payments](https://docs.paywithatoa.com/api-reference/refund/get-refund-payments.md)**
> >
> > List refunds for a given payment
>
> > **[initiate\_refund](https://docs.paywithatoa.com/api-reference/refund/initiate-refund.md)**
> >
> > Start a refund for a `COMPLETED` payment (full or partial)
>
> > **[cancel\_refund](https://docs.paywithatoa.com/api-reference/refund/cancel-refund.md)**
> >
> > Cancel an `INITIATED` refund — **production only**

> **Webhooks (3 tools)**
>
> > **[list\_merchant\_webhooks](https://docs.paywithatoa.com/api-reference/webhook/get-all-merchant-webhooks.md)**
> >
> > List all registered webhook endpoints
>
> > **[create\_webhook](https://docs.paywithatoa.com/api-reference/webhook/create-webhook-event.md)**
> >
> > Register a new webhook endpoint (supports OAuth 2.0 or Basic Auth)
>
> > **[delete\_webhook](https://docs.paywithatoa.com/api-reference/webhook/delete-webhook-event.md)**
> >
> > Remove a webhook endpoint

> **Bank Feeds (6 tools)**
>
> > **[initiate\_ais\_auth](https://docs.paywithatoa.com/api-reference/account-initiation-services/initiate-account-authorization.md)**
> >
> > Start the bank authorization flow — returns a URL the user must visit
>
> > **[fetch\_all\_accounts](https://docs.paywithatoa.com/api-reference/account-initiation-services/fetch-all-accounts.md)**
> >
> > List authorized bank accounts (requires completed authorization)
>
> > **[fetch\_account\_details](https://docs.paywithatoa.com/api-reference/account-initiation-services/fetch-account-details.md)**
> >
> > Get sort code, account number and bank name for an account
>
> > **[fetch\_account\_balance](https://docs.paywithatoa.com/api-reference/account-initiation-services/fetch-account-balance.md)**
> >
> > Get the current balance for an account
>
> > **[fetch\_account\_transactions](https://docs.paywithatoa.com/api-reference/account-initiation-services/fetch-account-transactions.md)**
> >
> > Retrieve paginated transactions for an account
>
> > **[revoke\_account\_access](https://docs.paywithatoa.com/api-reference/account-initiation-services/revoke-account-access.md)**
> >
> > Revoke access to one account, multiple accounts, or an entire session

> **Institutions (1 tool)**
>
> > **[get\_institutions](https://docs.paywithatoa.com/api-reference/institutions/institutions-controller.md)**
> >
> > List all supported banking institutions

> [!NOTE]
>
> 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

> **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:
>
> 1. Call `get_stores` to resolve your default store
>
> 2. Call `process_payment` with `amount: 25, currency: "GBP"`
>
> 3. Return a `paymentLink` and `qrCodeUrl` you share with the customer
>
> 4. The customer opens the link or scans the QR code to pay via their bank app
>
> > [!NOTE]
> >
> > `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.
>
> > [!NOTE]
> >
> > `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 |
>
> > [!WARNING]
> >
> > `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**
>
> > [!NOTE]
> >
> > **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.

> **Register a Webhook**
>
> 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 |
>
> > [!NOTE]
> >
> > 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:
>
> 1. Get a fresh token from the [Atoa Dashboard](https://dashboard.paywithatoa.co.uk/my-account/settings/api-access)
> 2. **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`)
> 3. **NPX mode:** confirm `ATOA_AUTH_TOKEN` and `ATOA_ENV` are set correctly in the `env` block of your config
> 4. 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**
>
> 1. **Restart your AI client** after updating the config file — most clients load MCP config only on startup
> 2. Verify the config file path and key name match your client (see the config tabs above)
> 3. **NPX mode:** check Node.js version — `node --version` must be 18+
> 4. **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`:
>
> 1. Share the `authorizationUrl` with the user
> 2. Wait for them to approve access in their banking app
> 3. 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 `hello@paywithatoa.co.uk` 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](https://dashboard.paywithatoa.co.uk/), 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`:
>
> 1. Check your internet connection
> 2. Verify no firewall rules are blocking outbound HTTPS (port 443)
> 3. Check [Atoa Status](https://atoa.instatus.com/) for service incidents

> **Too many requests (429)**
>
> The HTTP endpoint enforces rate limiting per token. If you receive a `429` response:
>
> 1. Wait briefly before retrying the request
> 2. Space out sequential tool calls
> 3. If you consistently hit rate limits for a production use case, contact `hello@paywithatoa.co.uk`

***

## Need Help?

Contact our team at `hello@paywithatoa.co.uk` or use chat support on the [Dashboard](https://dashboard.paywithatoa.co.uk/).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.