Docs & Usage Guide

Antom MCP Server

A Model Context Protocol (MCP) compatible server that integrates Ant International's Antom payment APIs, enabling AI assistants to handle payment and refund operations seamlessly.

Overview

The Antom MCP Server wraps Ant International's Antom payment APIs into standardized MCP tools, allowing AI assistants to securely process payment-related operations during conversations. With this server, you can create payment sessions, query transaction status, handle refunds, and more directly through AI interactions.

Features

💳 Payment Operations

Create Payment Session (create_payment_session): Generate payment sessions for client-side SDK integration
Query Payment Details (query_payment_detail): Retrieve transaction status and information for submitted payment requests
Cancel Payment (cancel_payment): Cancel payments when results are not returned within expected timeframes

💰 Refund Operations

Create Refund (create_refund): Initiate full or partial refunds against successful payments
Query Refund Details (query_refund_detail): Check refund status for previously submitted refund requests

Prerequisites

Before using the Antom MCP Server, ensure you have:

Python 3.11 or higher
uv (recommended package manager) or pip
Valid Antom Merchant Account with:
- Merchant Client ID (CLIENT_ID)
- Merchant RSA Private Key (MERCHANT_PRIVATE_KEY)
- Alipay RSA Public Key (ALIPAY_PUBLIC_KEY)
- Payment Redirect Return URL (PAYMENT_REDIRECT_URL)
- Payment Notification Callback URL (PAYMENT_NOTIFY_URL)

Quick Start

1. Installation

Direct Usage with uvx (Recommended)

uvx ant-intl-antom-mcp

Install from Source

git clone https://github.com/alipay/global-antom-mcp.git
cd global-antom-mcp
uv install

2. MCP Client Configuration

Add the following configuration to your MCP client:

{
  "mcpServers": {
    "antom-mcp-server": {
      "command": "uvx",
      "args": ["ant-intl-antom-mcp"],
      "env": {
        "GATEWAY_URL": "https://open-sea-global.alipay.com",
        "CLIENT_ID": "your_client_id_here",
        "MERCHANT_PRIVATE_KEY": "your_merchant_private_key_here",
        "ALIPAY_PUBLIC_KEY": "your_alipay_public_key_here",
        "PAYMENT_REDIRECT_URL": "/",
        "PAYMENT_NOTIFY_URL": "https://your-domain.com/payment/notify"
      }
    }
  }
}

3. Environment Variables

Variable	Required	Description
`GATEWAY_URL`	❌	Antom API gateway URL (defaults to https://open-sea-global.alipay.com)
`CLIENT_ID`	✅	Merchant client ID for identity verification
`MERCHANT_PRIVATE_KEY`	✅	Merchant RSA private key for request signing
`ALIPAY_PUBLIC_KEY`	✅	Alipay RSA public key for response verification
`PAYMENT_REDIRECT_URL`	❌	The user is redirected to after the payment is completed
`PAYMENT_NOTIFY_URL`	❌	Payment result notification callback URL

Integration Example

Here's how you can integrate the Antom MCP Server with your AI agent (using QwenAgent as an example):

import os
from qwen_agent.agents import Assistant

# Configure the MCP server as a tool
tools = [{
    "mcpServers": {
        "antom-mcp-server": {
            "command": "uvx",
            "args": ["ant-intl-antom-mcp"],
            "env": {
                "CLIENT_ID": os.getenv('CLIENT_ID'),
                "MERCHANT_PRIVATE_KEY": os.getenv('MERCHANT_PRIVATE_KEY'),
                "ALIPAY_PUBLIC_KEY": os.getenv('ALIPAY_PUBLIC_KEY'),
                "GATEWAY_URL": "https://open-sea-global.alipay.com",
                "PAYMENT_REDIRECT_URL": "/",
                "PAYMENT_NOTIFY_URL": "https://your-domain.com/notify"
            }
        }
    }
}]

# Create your AI assistant with payment capabilities
bot = Assistant(
    llm={'model': 'qwen-max', 'api_key': 'your-api-key'},
    function_list=tools,
    system_message="You are a helpful assistant with payment processing capabilities."
)

Changelog

See CHANGELOG.md for a detailed history of changes.

License

This project is licensed under the MIT License.

Acknowledgments

Model Context Protocol for the standard
Antom Integration for the Antom payment platform

Antom