Atoa MCP Server

The Atoa Model Context Protocol server allows you to integrate with Atoa payment APIs through function calling. This server provides tools to process payments, manage customers, handle refunds, access bank feeds, configure webhooks, and more.

Setup

You'll need an Atoa SDK Token from the Atoa Dashboard.

Quick Start

Run the interactive setup wizard:

npx @atoapayments/mcp init

This will guide you through setup and provide the configuration to add to your MCP client.

Manual Setup

npx -y @atoapayments/mcp --auth-token=YOUR_AUTH_TOKEN --env=sandbox

Replace YOUR_AUTH_TOKEN with your actual Atoa SDK token. Alternatively, set the ATOA_AUTH_TOKEN environment variable.

Note: Use --env=sandbox for testing and --env=production when you're ready to go live.

Client Configuration

Claude Desktop

Add the following to your claude_desktop_config.json (location guide):

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

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

Claude Code (CLI)

claude mcp add atoa -- npx -y @atoapayments/mcp --auth-token=YOUR_AUTH_TOKEN --env=sandbox

Cursor

Add to .cursor/mcp.json in your project root:

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

VS Code

Add to .vscode/mcp.json in your project root:

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

Gemini CLI

gemini mcp add -s user -- atoa npx -y @atoapayments/mcp --auth-token=YOUR_AUTH_TOKEN --env=sandbox

Windsurf

Add to your Windsurf MCP config:

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

Configuration Options

| Flag | Required | Default | Description | | --- | --- | --- | --- | | --auth-token | Yes | — | Atoa SDK access token | | --env | No | sandbox | sandbox or production | | --payment-redirect-url | No | — | Redirect URL after payment completion | | --ais-redirect-url | No | — | Redirect URL after bank authorization |

Available Tools

Tools are available across Payments, Customers, Payment Methods, Card on File, Refunds, Webhooks, Bank Feeds (AIS), and more.

See the Atoa MCP documentation for the full list of tools and debugging guides.

Troubleshooting

| Problem | Fix | | --- | --- | | Merchant not found | Check your auth token is valid and active in the Atoa Dashboard | | Connection timeout | Verify your network can reach mcp.atoa.me | | cancel_refund fails in sandbox | This is production-only. Use refundNotes: "FAILURE TEST" with initiate_refund to simulate | | Store not found | Verify the store is enabled in the Atoa Dashboard |

License

Proprietary - Atoa Payments Limited