PayCow
MCP Server
Enable AI agents (Claude, Cursor, Antigravity, ChatGPT, and custom support or commerce bots) to create non-custodial USDT payment sessions for end-users and verify settlement status via local stdio or hosted HTTP JSON-RPC 2.0.
@paycow/mcp-server
Zero-dependency Node.js 18+ stdio package plus hosted HTTP MCP endpoint at https://paycow.net/mcp with OAuth 2.0 + PKCE discovery.
Local stdio setup (Claude / Cursor / Antigravity)
The downloadable package requires Node.js 18 or newer and has zero external npm dependencies. Extract paycow-mcp-server.zip and point your MCP client configuration to bin/paycow-mcp.js:
{
"mcpServers": {
"paycow": {
"command": "node",
"args": ["/path/to/paycow-mcp-server/bin/paycow-mcp.js"],
"env": {
"PAYCOW_API_KEY": "cow-your-api-key",
"PAYCOW_API_SECRET": "cow_sec_your_api_secret",
"PAYCOW_BASE_URL": "https://paycow.net"
}
}
}
}
PAYCOW_BASE_URL defaults to https://paycow.net if omitted. To run the server directly or execute the included unit tests:
cd paycow-mcp-server npm test PAYCOW_API_KEY=cow-your-api-key PAYCOW_API_SECRET=cow_sec_your_api_secret npm start
Hosted HTTP MCP endpoint (/mcp)
PayCow exposes a hosted JSON-RPC 2.0 MCP endpoint at https://paycow.net/mcp (64 KB max JSON payload). Send GET /mcp to inspect server metadata, supported authentication methods, and tool summaries:
curl https://paycow.net/mcp
Send JSON-RPC 2.0 requests to POST https://paycow.net/mcp. Discovery methods (initialize, ping, tools/list) do not require credentials; tool execution (tools/call) requires authentication:
curl -X POST https://paycow.net/mcp \
-H "Content-Type: application/json" \
-H "x-api-key: cow-your-api-key" \
-H "x-api-secret: cow_sec_your_api_secret" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "create_payment",
"arguments": {
"userId": "chat-user-42",
"amount": 25,
"network": "TRC20",
"idempotencyKey": "chat-order-42-01"
}
}
}'
Authentication & OAuth 2.0
POST https://paycow.net/mcp accepts three credential mechanisms for tools/call:
| Method | Header | Best For |
|---|---|---|
| API Key & Secret | x-api-key + x-api-secret |
Direct server-to-server bots and custom HTTP MCP clients |
| HTTP Basic Auth | Authorization: Basic base64(apiKey:apiSecret) |
Clients with built-in Basic credential configuration |
| OAuth 2.0 Bearer | Authorization: Bearer <access_token> |
Remote MCP connectors (Claude Connectors, ChatGPT, OAuth clients) |
When an unauthenticated tools/call is sent to POST /mcp, the server responds with HTTP 401 and a WWW-Authenticate header pointing to the OAuth protected resource metadata endpoint:
| Endpoint | Purpose |
|---|---|
GET /.well-known/oauth-protected-resource |
Declares resource (/mcp), authorization_servers, and supported scopes (payments:write, payments:read) |
GET /.well-known/oauth-authorization-server |
OAuth 2.0 metadata: endpoints, authorization_code & client_credentials grants, PKCE (S256, plain) |
GET / POST /oauth/authorize |
Interactive merchant consent form validating client_id (API Key) and api_secret; issues a 5-minute authorization code |
POST /oauth/token |
Exchanges an authorization code (with PKCE code_verifier) or client_credentials for an AES-256-GCM sealed Bearer token (24-hour TTL / 86400s) |
Example obtaining a Bearer token via client_credentials (supports both client_secret_post and client_secret_basic):
curl -X POST https://paycow.net/oauth/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=cow-your-api-key&client_secret=cow_sec_your_api_secret"
JSON-RPC 2.0 lifecycle
Both the local stdio binary and POST /mcp implement MCP protocol version 2025-03-26:
| Method | Behavior |
|---|---|
initialize |
Returns protocolVersion: "2025-03-26", capabilities: { tools: {} }, and serverInfo (paycow-mcp-server v1.0.0) |
notifications/initialized |
Notification acknowledged with HTTP 202 (empty body) on HTTP, or no output on stdio |
ping |
Health check returning an empty result object {} |
tools/list |
Returns the full tool definitions and JSON Schema inputSchema for create_payment and get_payment_status |
tools/call |
Executes the named tool and returns both content: [{ type: "text", text }] and structuredContent |
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-03-26",
"capabilities": {},
"clientInfo": { "name": "my-agent", "version": "1.0.0" }
}
}
Tools reference
create_payment
Calls POST /api/payment/create to open a non-custodial USDT payment session. When idempotencyKey is provided, it is forwarded in both the JSON body and the Idempotency-Key HTTP header.
| Argument | Type | Required | Description |
|---|---|---|---|
userId |
string |
Yes | Your application or AI agent end-user identifier (e.g. chat-user-42) |
amount |
number |
Yes | Requested payment amount in USDT or USDC (must be > 0) |
network |
string |
Yes | Blockchain network: TRC20, ERC20, BEP20, POLYGON, ARBITRUM, BASE (USDC only), or AVAX |
currency |
string |
No | Stablecoin currency: USDT (default; not supported on BASE) or USDC (not supported on TRC20) |
paymentMethod |
string |
No | ONCHAIN (default) or ONRAMP (eligible Pro, Scale, and Enterprise plans) |
addressSerialNo |
string |
No | Specific merchant wallet serial number configured in your PayCow dashboard |
idempotencyKey |
string |
No | Unique key per order or attempt to prevent duplicate payment sessions |
Returns sessionId, paymentUrl, paymentReference, paymentMethod, amountRequested, payableAmount, amount, depositAddress, addressSerialNo, walletLabel, and expiresAt.
payableAmount (not amountRequested). PayCow may allocate a unique micro-amount when multiple active payments share the same destination address and network.{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "{\n \"sessionId\": \"66ce30d74c0c51a48f2d2903\",\n \"paymentUrl\": \"https://paycow.net/pay/66ce30d74c0c51a48f2d2903\",\n \"paymentReference\": \"PAY-9F2A1C\",\n \"paymentMethod\": \"ONCHAIN\",\n \"amountRequested\": 25,\n \"payableAmount\": 25.0014,\n \"amount\": 25.0014,\n \"depositAddress\": \"T...\",\n \"addressSerialNo\": \"WAL-1002\",\n \"walletLabel\": \"Main TRC20\",\n \"expiresAt\": \"2026-11-17T23:30:00.000Z\"\n}"
}
],
"structuredContent": {
"sessionId": "66ce30d74c0c51a48f2d2903",
"paymentUrl": "https://paycow.net/pay/66ce30d74c0c51a48f2d2903",
"paymentReference": "PAY-9F2A1C",
"paymentMethod": "ONCHAIN",
"amountRequested": 25,
"payableAmount": 25.0014,
"amount": 25.0014,
"depositAddress": "T...",
"addressSerialNo": "WAL-1002",
"walletLabel": "Main TRC20",
"expiresAt": "2026-11-17T23:30:00.000Z"
},
"isError": false
}
}
get_payment_status
Calls GET /api/payment/status/:sessionId to retrieve authoritative settlement state for a session.
| Argument | Type | Required | Description |
|---|---|---|---|
sessionId |
string |
Yes | The PayCow payment sessionId returned by create_payment |
Returns sessionId, userId, amountRequested, payableAmount, amountReceived, currencyInfo, depositAddress, depositNetwork, status, confirmations, paymentReference, txHash, expiresAt, and createdAt.
Possible status values: PENDING, DETECTED, CONFIRMING, PAID, EXPIRED, or REJECTED.
Errors & handling
| Code / Field | Meaning |
|---|---|
HTTP 401 / JSON-RPC -32001 |
Missing or invalid credentials on HTTP tools/call; includes WWW-Authenticate OAuth resource metadata header |
JSON-RPC -32700 |
Malformed JSON line received on stdio transport |
JSON-RPC -32600 |
Invalid JSON-RPC 2.0 request envelope |
JSON-RPC -32601 |
Unknown JSON-RPC method |
HTTP 500 / JSON-RPC -32603 |
Unexpected internal MCP server error |
result.isError: true |
Tool-level validation failure (e.g. invalid network or amount <= 0) or upstream PayCow API error (e.g. 401, 403 trial limit, 404 session not found); details are in result.content[0].text |
Non-custodial security model
PAYCOW_API_KEY and PAYCOW_API_SECRET (or an OAuth 2.0 Bearer token derived from them). Funds settle directly to the merchant's configured wallet; agents cannot access private keys, modify payout wallets, or initiate withdrawals.