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 the payable_network values (TON for GRAM on TON, TON_USDT for USDT on TON, TRON, BASE, BSC). 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.