recv MCP Server

Model Context Protocol (MCP) server for integrating recv Payment Gateway into AI agents (Claude, Cursor, etc.).

Install

Published to npm as recv-mcp; MCP hosts can run it with npx -y recv-mcp. To run from source: npm install (compiles dist/ via the prepare script), then node dist/index.js or npm run dev.

Releasing a new version: bump version in package.json, then push a matching tag (git tag mcp-v1.0.1 && git push origin mcp-v1.0.1) — the release-mcp workflow builds and publishes with npm provenance (requires the NPM_TOKEN repository secret).

Features

Tools

• get_account: Check the current console workspace, plan, and available plans.
• bootstrap_agent_workspace: Create a new trial workspace for a fully autonomous agent.
• create_subscription_checkout: Create a recv billing checkout for Merchant, Developer, or Business.
• get_checkout_invoice: Poll a public checkout invoice until payment is detected.
• create_api_key: Create a developer API key after an API-capable plan is active.
• create_webhook_endpoint: Register a webhook endpoint for payment events.
• create_invoice: Create payment requests.
• get_invoice: Check payment status.
• list_invoices: View recent activity.
• verify_webhook: Securely validate incoming notifications.
• list_supported_networks: Check supported blockchains.
• simulate_payment: Test payments in Sandbox.

Resources

• recv://docs/auth: Authentication guide.
• recv://docs/invoices: API usage.
• recv://docs/webhooks: Integration guide.
• recv://docs/errors: Error codes and limits.
• recv://docs/mcp: Agent onboarding guide.

Configuration

The server can run in two modes.

Console/self-service mode lets an agent buy or upgrade the recv workspace plan and create API credentials:

• RECV_ACCESS_TOKEN: recv app bearer token from /api/auth/*. If the agent does not have one yet, call bootstrap_agent_workspace first and persist the returned token.
• RECV_APP_URL: (Optional) App/API origin for console endpoints (default is derived from RECV_API_URL, e.g. https://recv.money).

Developer API mode lets an agent create and manage payment invoices:

• RECV_API_KEY: Your recv API key.
• RECV_WEBHOOK_SECRET: Your webhook signing secret (for verification).
• RECV_API_URL: (Optional) Base URL for the API (default: https://recv.money/v1).
• RECV_DOCS_URL: (Optional) Base URL for raw docs (default: https://recv.money/en/docs).

Agent onboarding flow

Use the existing Merchant plan for checkout-only merchants. Do not create a separate AI plan by default: AI agents that need API access should buy developer or business, because those plans already include API keys, webhooks, limits, and subscription billing.

1. If there is no console token, call bootstrap_agent_workspace. The server keeps the returned token in memory for subsequent calls; persist it as RECV_ACCESS_TOKEN to survive a server restart.
2. Call get_account to inspect the active workspace and plan.
3. If the plan does not include API access, call create_subscription_checkout with plan_code: "developer" and a payable network.
4. Send the returned checkout_url to the payer, or open it in the host app.
5. Poll get_checkout_invoice with the returned public_id until status is paid.
6. Call create_api_key. The server uses the returned secret immediately; store it as RECV_API_KEY to survive a restart.
7. Optionally call create_webhook_endpoint. The returned webhook secret is also used immediately; store it as RECV_WEBHOOK_SECRET to survive a restart.
8. Use create_invoice, get_invoice, and list_invoices for customer payments.

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "recv": {
      "command": "npx",
      "args": ["-y", "recv-mcp"],
      "env": {
        "RECV_ACCESS_TOKEN": "your_recv_console_token_here",
        "RECV_API_KEY": "your_api_key_here",
        "RECV_WEBHOOK_SECRET": "your_secret_here"
      }
    }
  }
}

Development

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