MCP / AI Agents

recv ships a Model Context Protocol (MCP) server that exposes the payment gateway to AI agents as tools and resources. Any MCP-compatible client — Claude Desktop, Cursor, and others — can use it to create invoices, check payment status, verify webhooks, and look up supported networks, all in natural language.

The server is recv-mcp and runs locally over stdio. Under the hood it calls the same recv API documented elsewhere in these docs. It can also bootstrap a new agent workspace, create a recv subscription checkout, and issue API credentials after the subscription is paid.

Configuration

The server reads these environment variables:

Claude Desktop

Add the server to claude_desktop_config.json (the package is published to npm as recv-mcp; to run from source instead, build it with cd mcp-server && npm install and use node /path/to/recv/mcp-server/dist/index.js):

{
  "mcpServers": {
    "recv": {
      "command": "npx",
      "args": ["-y", "recv-mcp"],
      "env": {
        "RECV_ACCESS_TOKEN": "your_console_token_here",
        "RECV_API_KEY": "test_your_key_here",
        "RECV_WEBHOOK_SECRET": "whsec_your_secret_here"
      }
    }
  }
}

Cursor

Add the same mcpServers block to Cursor's MCP settings (Settings → MCP), then reload. The recv tools appear to the agent automatically.

Local development

cd mcp-server
npm install   # also compiles dist/ via the prepare script
npm run dev   # or: npm start

Tools

The agent can call these tools.

bootstrap_agent_workspace

Create a new trial workspace for a fully autonomous agent. The MCP server keeps the returned token or access_token in memory for subsequent self-service calls. Persist it as RECV_ACCESS_TOKEN to survive a server restart.

get_account

Return the authenticated workspace, active plan, and available paid plans. Requires RECV_ACCESS_TOKEN.

create_subscription_checkout

Create a recv billing checkout for the current workspace. Requires RECV_ACCESS_TOKEN.

get_checkout_invoice

Read a public checkout invoice by public_id. Use it to poll a subscription checkout until status is paid.

create_api_key

Create a developer API key after the workspace has an API-capable plan. Requires RECV_ACCESS_TOKEN.

create_webhook_endpoint

Register a webhook endpoint after the workspace has webhooks enabled. Requires RECV_ACCESS_TOKEN.

create_invoice

Create a new payment invoice.

The tool POSTs the arguments directly to /v1/invoices. The created invoice's environment follows the API key (test_ → test). See Invoices.

get_invoice

Retrieve status and details of an invoice.

Calls GET /v1/invoices/{id}.

list_invoices

List recent invoices with pagination.

Calls GET /v1/invoices?page=&page_size=.

simulate_payment

Mark a test invoice as paid without an on-chain transfer.

Calls POST /v1/test/invoices/{id}/simulate-payment. Requires an test_ key.

verify_webhook

Verify a webhook signature locally using RECV_WEBHOOK_SECRET. The tool reproduces the production signing scheme exactly: it computes v1= + HMAC-SHA256 of <timestamp>.<raw_body> and compares it against the provided signature with a constant-time check.

Pass the body bytes verbatim. Re-encoding the JSON (which can reorder keys or change whitespace) changes the hash and the check will fail. If RECV_WEBHOOK_SECRET is unset, the tool returns an error. See Webhooks for the full signing scheme.

list_supported_networks

List the payment options recv supports. Takes no parameters and returns a static summary of network/asset pairs (TON/GRAM, TON/USDT, TRON/USDT, SOLANA/SOL, SOLANA/USDT, SOLANA/USDC, BASE/USDT, BASE/USDC, ARBITRUM/USDT, ARBITRUM/USDC, BSC/BNB, BSC/USDT). See Supported Networks for the authoritative list.

Resources

The server also exposes documentation as MCP resources, which the agent can read for context. Each is fetched from ${RECV_DOCS_URL}/raw/<slug>:

Walkthrough: an AI agent accepts a crypto payment

For a brand-new autonomous agent:

1. Call bootstrap_agent_workspace. The returned access token is available to subsequent calls in the same MCP process; store it as RECV_ACCESS_TOKEN for future processes.
2. Call create_subscription_checkout with plan_code: "developer".
3. Open or return the checkout URL, then poll get_checkout_invoice until the subscription invoice is paid.
4. Call create_api_key. The returned secret is used by subsequent invoice tools in the same process; store it as RECV_API_KEY for future processes.
5. Optionally call create_webhook_endpoint. The returned secret is used by verify_webhook in the same process; store it as RECV_WEBHOOK_SECRET for future processes.

With the server configured against an test_ or live_ key, you can drive the customer payment flow conversationally:

1. You: "Create a $25 USDT invoice on TRON for order #5512." The agent calls create_invoice and reads back the public_id, destination_address, and checkout_url.
2. You: "Has it been paid yet?" The agent calls get_invoice with the returned id and reports status: awaiting_payment.
3. You: "Simulate the payment so I can test my fulfillment." The agent calls simulate_payment; the invoice flips to paid and a webhook fires.
4. You: "Verify this webhook for me — here are the raw body, timestamp, and signature headers." The agent calls verify_webhook with raw_body, timestamp, and signature, and reports whether the signature is valid.
5. You: "Which networks can I charge on?" The agent calls list_supported_networks.

Because every tool ultimately hits the same /v1 API, the agent's actions are subject to the same scopes, rate limits, and idempotency rules as any other integration.