Agent Toolkit Quick Start

MCP Server

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

LangChain Integration

Learn how to build your AI agent with the EVO Payment Agent Toolkit.

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.

1. Install Dependencies

pip install evocloud-agent-toolkit langchain langchain-openai

2. Configure Environment Variables

cp env.example .env
# Edit the .env file and fill in your actual configuration
EVOCLOUD_BASE_URL=https://online-uat.everonet.com
EVOCLOUD_SIGN_KEY=your_sign_key
EVOCLOUD_SID=your_sid
EVOCLOUD_WEBHOOK_URL=https://your-domain.com/webhook  # optional
OPENAI_API_KEY=your_openai_api_key

3. Integrate with LangChain Agent

from evocloud_agent_toolkit.langchain import EvoCloudToolkit
from langchain.agents import create_openai_functions_agent, AgentExecutor
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain_openai import ChatOpenAI

# Initialize toolkit and model
toolkit = EvoCloudToolkit()
tools = toolkit.get_tools()
llm = ChatOpenAI(model="gpt-4", temperature=0)

# Create prompt template
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a professional payment assistant who can help users handle LinkPay-related business."),
    ("user", "{input}"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

# Create and run the Agent
agent = create_openai_functions_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools)

# Interact via natural language
response = agent_executor.invoke({
    "input": "Please create an order, order number ORDER_123, amount $99.99, product is Premium Service."
})
print(response["output"])