Documentation/MCP Server
MODEL CONTEXT PROTOCOL (MCP)

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.

MCP

@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.

MCP 2025-03-26 STDIO & HTTP OAUTH 2.0 + PKCE NON-CUSTODIAL

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.

Always instruct the user to send the exact 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 is strictly non-custodial. AI agents authenticate with the merchant's own 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.