MCP Server Preview

The EVO Payment MCP server defines a set of tools that AI agents can use to interact with the EVO Payment API.

Explore this SDK to integrate EVO Payment into agentic workflows. Because agent behavior is non-deterministic, use the SDK in a sandbox and run evaluations to assess your application’s performance.

Prerequisites

MCP Client

1. Ensure you have a functional MCP client. For detailed client list, please refer to https://modelcontextprotocol.io/clients
2. Ensure you have installed uv, please refer to the documentation https://docs.astral.sh/uv/getting-started/installation/

Environment Variables

Before using LinkPay MCP, you need to configure the following environment variables:

Environment Variable	Description	Required
EVOCLOUD_BASE_URL	EvoCloud API base URL (defaults to UAT service)	Yes
EVOCLOUD_SID	EvoCloud merchant ID	Yes
EVOCLOUD_SIGN_KEY	EvoCloud signature key	Yes
EVOCLOUD_WEBHOOK_URL	Payment callback URL	No

MCP Server Configuration

Add the following configuration to your MCP client configuration file:

{
  "mcpServers": {
    "linkpay": {
      "command": "uvx",
      "args": ["--from", "evocloud_agent_toolkit", "linkpaymcp", "stdio"],
      "env": {
        "EVOCLOUD_BASE_URL": "https://counter-uat.everonet.com",
        "EVOCLOUD_SID": "Your merchant ID",
        "EVOCLOUD_SIGN_KEY": "Your signature key",
        "EVOCLOUD_WEBHOOK_URL": "https://example.com/webhook"
      }
    }
  }
}

Feature Overview

LinkPay MCP provides the following core features:

1. Generate Merchant Order ID

• Function name: generate_merchant_order_id
• Description: Generate a unique merchant order ID
• Parameters:
  • prefix (optional): Order ID prefix, defaults to "LINKPAY"

2. Create Payment Order

• Function name: create_linkpay_order
• Description: Create a LinkPay payment order
• Parameters:
  • merchant_order_id (required): Merchant order ID
  • currency (required): Currency code, e.g., "USD", "CNY"
  • amount (required): Payment amount
  • merchant_order_time (optional): Order time
  • goods_name (optional): Product name
  • goods_description (optional): Product description
  • trade_type (optional): Transaction type
  • return_url (optional): Return URL after payment completion
  • webhook_url (optional): Payment status callback URL
  • enabled_payment_methods (optional): List of supported payment methods
  • valid_time (optional): Order validity time (minutes)

3. Query Order Status

• Function name: query_linkpay_order
• Description: Query LinkPay order status
• Parameters:
  • merchant_order_id (required): Merchant order ID

4. Create Refund

• Function name: create_linkpay_refund
• Description: Create a LinkPay refund request
• Parameters:
  • original_merchant_order_id (required): Original order ID
  • merchant_trans_id (required): Refund transaction ID
  • currency (required): Currency code
  • refund_amount (required): Refund amount
  • merchant_trans_time (optional): Refund time
  • reason (optional): Refund reason
  • description (optional): Refund description

5. Query Refund Status

• Function name: query_linkpay_refund
• Description: Query LinkPay refund status
• Parameters:
  • merchant_trans_id (required): Refund transaction ID

Usage Examples

1. Configure LinkPay MCP service in Cursor

Configure the service as follows:

Save the configuration and check if the LinkPay service is running normally in the MCP tools list

2. Create LinkPay transaction order

Security Considerations

1. Key Security: Ensure sensitive information like EVOCLOUD_SIGN_KEY is stored securely, do not hardcode in the source code
2. HTTPS: Production environment must use HTTPS protocol
3. Signature Verification: Callback webhooks should verify the validity of request signatures
4. Order Idempotency: Ensure the same merchant_order_id does not create duplicate orders
5. Amount Validation: Validate the reasonableness of amounts before processing payments