---
title: MCP Server
description: Connect AI assistants to the Airpay Payment Gateway using the Model Context Protocol.
---

The **Airpay MCP Server** lets AI assistants — Claude, Cursor, VS Code, ChatGPT, Perplexity — interact with Airpay Payment Gateway through natural language. Once connected, your AI can verify payments, generate QR codes, and process refunds directly in the chat.

**Hosted MCP endpoint:** `https://mcp.airpay.co.in/mcp`

## Features

- **Payment Verification:** Check the status of any transaction by order ID, transaction ID, or RRN — get real-time payment status, amounts, and processing details.
- **Refund Processing:** Initiate full or partial refunds with a built-in two-phase confirmation guard — the AI previews the refund and waits for your explicit approval before processing.
- **UPI QR Code Generation:** Generate dynamic UPI QR codes for any amount and customer — ready to share instantly for payment collection.
- **UPI Address Validation:** Validate any UPI Virtual Payment Address (VPA) before initiating a transfer to prevent failed payments.
- **Subscription Management:** Check the status of eNACH and Standing Instruction mandates — see whether a subscription is active, paused, or completed.
- **Bank & Payment Options:** Retrieve the list of supported banks and payment modes available for your merchant account.
- **Built-in Security Guardrails:** Read-only mode disables all write tools with a single environment variable. Selective toolsets let you expose only the tools your workflow needs.
- **Stateless HTTP Transport:** Each tool call is a self-contained HTTP request — no session state, safe to restart, compatible with load balancers and shared deployments.

## How It Works

**Remote Hosted** — OAuth 2 authentication is required once before your AI client can call any tool. After that, tool calls flow directly through the hosted server.

```mermaid
sequenceDiagram
    actor User
    participant AI as AI Client
    participant Auth as OAuth 2
    participant GW as Airpay Gateway

    Note over User,Auth: One-time login
    User->>AI: Connect to MCP Server
    AI->>Auth: Redirect to login
    User->>Auth: Enter credentials
    Auth-->>AI: Access token

    Note over User,GW: Tool calls
    User->>AI: "Status of ORD123?"
    AI->>GW: airpay_verify_order (token)
    GW-->>AI: Payment status
    AI-->>User: "ORD123 paid ₹500"
```

**Self-Hosted** — No OAuth 2 required. Your AI client connects directly to your local server using the credentials already configured in `.env`.

```mermaid
sequenceDiagram
    actor User
    participant AI as AI Client
    participant MCP as MCP Server
    participant GW as Airpay Gateway

    User->>AI: "Status of ORD123?"
    AI->>MCP: airpay_verify_order (.env creds)
    MCP->>GW: API request
    GW-->>MCP: Payment status
    MCP-->>AI: Result
    AI-->>User: "ORD123 paid ₹500"
```

## Prerequisites

- **Go 1.25+** or **Docker**
- An Airpay merchant account with API credentials (Merchant ID, username, password, secret key, OAuth2 client ID and secret)

## Setup

### Binary (Go)

**1. Clone the repository**

```bash
git clone https://github.com/airpay/airpay-mcp-server.git
cd airpay-mcp-server
go mod download
```

**2. Configure credentials**

```bash
cp .env.example .env
```

Edit `.env` with your Airpay credentials:

```ini
AIRPAY_MERCHANT_ID=your_merchant_id
AIRPAY_USERNAME=your_username
AIRPAY_PASSWORD=your_password
AIRPAY_SECRET=your_secret_key
AIRPAY_CLIENT_ID=your_oauth2_client_id
AIRPAY_CLIENT_SECRET=your_oauth2_client_secret
PAYMENT_DOMAIN=https://yourstore.com
ENVIRONMENT=sandbox
```

**3. Build and run**

<Tabs syncKey="os">
<TabItem label="Linux / macOS">

```bash
go build -o airpay-mcp-server ./cmd/airpay-mcp-server
./airpay-mcp-server
# Running over Streamable HTTP on :8888
```

### Windows

```powershell
go build -o airpay-mcp-server.exe ./cmd/airpay-mcp-server
.\airpay-mcp-server.exe
# Running over Streamable HTTP on :8888
```

### go run (any OS)

```bash
go run ./cmd/airpay-mcp-server
# Running over Streamable HTTP on :8888
```

</TabItem>
<TabItem label="Docker">

**1. Clone and configure**

```bash
git clone https://github.com/airpay/airpay-mcp-server.git
cd airpay-mcp-server
cp .env.example .env
```

Edit `.env` with your Airpay credentials (same variables as the Binary tab).

**2. Run with Docker**

```bash
docker build -t airpay-mcp-server .
docker run --env-file .env -p 8888:8888 airpay-mcp-server
```

</TabItem>
</Tabs>


## Connect Your AI Client

There are two ways to connect your AI client to the Airpay MCP Server:

| Method | Best For |
|--------|----------|
| **Remote Hosted** *(recommended)* | Most users — no setup, always up to date, hosted by Airpay at `https://mcp.airpay.co.in/mcp` |
| **Self-Hosted (Local)** | Developers who need full control or want to run in a private network |

:::tip[Recommended]
Use the Airpay-hosted MCP Server at `https://mcp.airpay.co.in/mcp`. No infrastructure to manage just point your AI client at the URL and you're ready.
:::

### Remote Hosted *(Recommended)*

Point your AI client at the Airpay-hosted server. On first connection, you will be redirected through an **OAuth 2 login flow** — log in with your Airpay merchant credentials to authorize access. After that, your AI client uses the issued token automatically for all subsequent tool calls.

**MCP endpoint:** `https://mcp.airpay.co.in/mcp`

### Claude Desktop

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

```json
{
  "mcpServers": {
    "airpay": {
      "type": "http",
      "url": "https://mcp.airpay.co.in/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

### Cursor

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

```json
{
  "mcpServers": {
    "airpay": {
      "type": "http",
      "url": "https://mcp.airpay.co.in/mcp"
    }
  }
}
```

Restart Cursor after saving.

### VS Code

Create `.vscode/mcp.json` in your workspace root:

```json
{
  "servers": {
    "airpay": {
      "type": "http",
      "url": "https://mcp.airpay.co.in/mcp"
    }
  }
}
```

Reload the VS Code window (`Ctrl+Shift+P` → Reload Window).

### Claude

1. Visit the **Anthropic MCP Directory** or open **Claude.ai → Settings → Integrations**
2. Search for **Airpay MCP Server**
3. Click **Connect**
4. A browser window will open — log in with your Airpay merchant credentials to complete authentication
5. Once authenticated, the Airpay tools are available immediately in Claude

Ask Claude: *"What Airpay payment tools are available?"*

### ChatGPT

1. Open **ChatGPT** and go to **Explore → Plugins** or **Settings → Connected Apps**
2. Search for **Airpay MCP Server**
3. Click **Enable**
4. Log in with your Airpay merchant credentials when prompted
5. The Airpay tools are now available in your ChatGPT conversations

Ask ChatGPT: *"What Airpay payment tools are available?"*

### Self-Hosted (Local)

Run your own instance for private or on-premise deployments. **No OAuth 2 required** — your AI client connects directly to the local server using the credentials you configured in `.env`. See [Setup](#setup) above to build and start the server, then point your client at `http://localhost:8888/mcp`.

### Claude Desktop

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

```json
{
  "mcpServers": {
    "airpay": {
      "type": "http",
      "url": "http://localhost:8888/mcp"
    }
  }
}
```

Restart Claude Desktop after saving.

### Cursor

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

```json
{
  "mcpServers": {
    "airpay": {
      "type": "http",
      "url": "http://localhost:8888/mcp"
    }
  }
}
```

Restart Cursor after saving.

### VS Code

Create `.vscode/mcp.json` in your workspace root:

```json
{
  "servers": {
    "airpay": {
      "type": "http",
      "url": "http://localhost:8888/mcp"
    }
  }
}
```

Reload the VS Code window (`Ctrl+Shift+P` → Reload Window).

## Available Tools

| Tool | Read-Only | Description |
|------|-----------|-------------|
| `airpay_verify_order` | ✅ | Check payment status by order ID, transaction ID, or RRN |
| `airpay_get_bank_list` | ✅ | List supported banks and payment options |
| `airpay_pos_transaction_detail` | ✅ | Get POS terminal transaction details |
| `airpay_initiate_refund` | ❌ | Initiate full or partial refund — requires user confirmation |
| `airpay_validate_vpa` | ✅ | Validate a UPI Virtual Payment Address |
| `airpay_generate_qr` | ❌ | Generate a dynamic UPI QR code for payment |
| `airpay_check_subscription_status` | ✅ | Check eNACH / SI subscription status |

**Refund confirmation:** Before any refund is processed, the AI will show you a preview and ask for explicit approval. The refund only executes after you confirm.

## Configuration

All configuration is via environment variables.

**Required:**

| Variable | Description |
|----------|-------------|
| `AIRPAY_MERCHANT_ID` | Your Airpay merchant ID |
| `AIRPAY_USERNAME` | API username |
| `AIRPAY_PASSWORD` | API password |
| `AIRPAY_SECRET` | Secret key |
| `AIRPAY_CLIENT_ID` | OAuth2 client ID |
| `AIRPAY_CLIENT_SECRET` | OAuth2 client secret |
| `PAYMENT_DOMAIN` | Merchant domain for QR/bank-list requests (e.g. `https://yourstore.com`) |

**Optional:**

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8888` | Server listen port |
| `ENVIRONMENT` | `sandbox` | `sandbox` or `production` |
| `TOOLSETS` | `all` | Comma-separated toolsets: `payments`, `refunds`, `qr_upi`, `subscriptions` |
| `READ_ONLY` | `false` | Set `true` to disable all write tools |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn`, or `error` |

:::note[Sandbox vs production]
Use `ENVIRONMENT=sandbox` while testing. Switch to `ENVIRONMENT=production` only with live merchant credentials.
:::

## Examples

### Example 1: Verify a Payment

**User prompt:**

> "What is the status of order ORD123456?"

**What happens:** The AI looks up the order and returns the current payment status.

```
User: What is the status of order ORD123456?
Assistant: Let me check that order for you.
→ Calls: airpay_verify_order(orderid="ORD123456")
→ Returns:
  Order: ORD123456
  Status: SUCCESS
  Amount: ₹500.00
  Transaction ID: 7891234
```

---

### Example 2: Process a Refund

**User prompt:**

> "Refund ₹250 for transaction 7891234."

**What happens:** The AI previews the refund and waits for explicit confirmation before processing.

```
User: Refund ₹250 for transaction 7891234
Assistant: I'll initiate a refund preview for you.
→ Calls: airpay_initiate_refund(transactions=[{ap_transactionid: "7891234", amount: "250.00"}])
→ Returns:
  Preview — Refund ₹250.00 for transaction 7891234
  Confirmation required to proceed.

User: Yes, confirm
Assistant: Processing the refund now.
→ Calls: airpay_initiate_refund(transactions=[...], confirmed=true, confirmation_token="abc123")
→ Returns: Refund of ₹250.00 initiated successfully for transaction 7891234.
```

---

### Example 3: Generate a UPI QR Code

**User prompt:**

> "Generate a UPI QR code for ₹500 for customer John Doe, john@example.com."

**What happens:** The AI generates a dynamic UPI QR code for the specified amount and customer.

```
User: Generate a UPI QR code for ₹500 for customer John Doe, john@example.com
Assistant: Generating the QR code now.
→ Calls: airpay_generate_qr(orderid="ORD789", amount="500.00",
    customer_name="John Doe", customer_email="john@example.com")
→ Returns:
  QR code generated for order ORD789
  Amount: ₹500.00
  Share the QR with the customer to complete payment.
```

---

### Example 4: Validate a UPI Address

**User prompt:**

> "Is merchant@okaxis a valid UPI address?"

**What happens:** The AI validates the UPI Virtual Payment Address before a payment is initiated.

```
User: Is merchant@okaxis a valid UPI address?
Assistant: Let me validate that UPI address.
→ Calls: airpay_validate_vpa(vpa="merchant@okaxis")
→ Returns: merchant@okaxis is a valid UPI Virtual Payment Address.
```

---

### Example 5: Check a Subscription

**User prompt:**

> "What is the status of subscription SUB123456?"

**What happens:** The AI looks up the eNACH or SI mandate and returns its current status.

```
User: What is the status of subscription SUB123456?
Assistant: Let me check that subscription.
→ Calls: airpay_check_subscription_status(subscription_id="SUB123456")
→ Returns:
  Subscription: SUB123456
  Status: SUBSCRIBED
  Next debit scheduled as per the mandate cycle.
```