x402 MCP Payment Gateway

Connect any MCP-compatible AI agent (Cursor, Claude Desktop, and more) to paid APIs — with automatic x402 crypto payments and built-in compliance checks, handled transparently in the background.

How it works

1. Merchants register their APIs on the platform
2. You install this gateway — it fetches the available tool list automatically on startup
3. Your AI agent calls the tools — the gateway handles x402 payments, compliance checks, and returns the result

No manual payment steps. No extra code. Just configure and go.

Prerequisites

• Node.js 18+
• A gateway account — apply at Agentry Dashboard to obtain:
  • FACILITATE_USER_API_KEY — your API key (used to fetch the tool registry, resolve your buyer facilitateId, and run compliance checks)
• An EVM wallet private key — used to sign x402 payment authorizations (Base Sepolia testnet or mainnet)

Apply for a Gateway Account

1. Visit Agentry Dashboard and register an account
2. After logging in, go to Settings → API Keys page
3. Click Generate API Key to create your Gateway API Key (format: facilitate_...)
4. The gateway will automatically resolve your facilitateId on startup (no separate configuration needed)

Quick Start

Step 1 — Get your credentials from Agentry Dashboard

1. Visit Agentry Dashboard and sign up
2. Go to Settings → API Keys and click Generate API Key
3. Copy your API Key (format: facilitate_...)
4. The gateway resolves your buyer facilitateId automatically on startup — no separate ID configuration required

Prepare an EVM wallet private key — this is the wallet that will pay for API calls. The key never leaves your machine.

Step 2 — Install the package globally

npm install -g toani-mcp

Step 3 — Add to your MCP client

Paste the following into your MCP client's config file:

{
  "mcpServers": {
    "toani-mcp": {
      "command": "toani-mcp",
      "args": [],
      "env": {
        "EVM_PRIVATE_KEY": "0xYOUR_WALLET_PRIVATE_KEY",
        "FACILITATE_USER_API_KEY": "facilitate_YOUR_API_KEY"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add toani-mcp \
  -e EVM_PRIVATE_KEY=0xYOUR_WALLET_PRIVATE_KEY \
  -e FACILITATE_USER_API_KEY=facilitate_YOUR_API_KEY \
  -- toani-mcp

Cursor

Open Settings → MCP and click Edit mcp.json, then paste the config above.

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json and merge the mcpServers block above.

Claude Desktop (Windows)

Edit %APPDATA%\Claude\claude_desktop_config.json.

Other MCP clients

Any client that supports stdio MCP transport will work. Add the JSON block to wherever that client stores its MCP server configuration.

Environment Variables

| Variable | Required | Description | |----------|:--------:|-------------| | EVM_PRIVATE_KEY | ✅ | Your EVM wallet private key (0x...). Used to sign x402 payment authorizations. | | FACILITATE_USER_API_KEY | ✅ | Your API key (facilitate_...). Get from Agentry Dashboard (Settings → API Keys). Used to fetch the tool registry, resolve your buyer facilitateId, and run compliance checks. | | FACILITATE_ID | ❌ | Optional override for your buyer facilitateId. If unset, the gateway resolves it automatically from the Dashboard on startup. | | REGISTRY_REFRESH_INTERVAL | ❌ | How often (in seconds) to refresh the tool list. Default: 300. |

Built-in Tools

Once connected, your agent has access to two utility tools in addition to all registered merchant tools:

| Tool | Description | |------|-------------| | list_registered_tools | List all tools currently loaded in the gateway, with their descriptions and registration metadata. | | refresh_gateway_registry | Manually re-fetch the tool list. Useful after a merchant registers a new tool. |

Offline / Degraded Mode

The gateway caches the tool list locally at ~/.facilitate/tools-cache.json. If the registry service is unreachable on startup, it automatically falls back to the cached version so you can keep working.

Security Notes

• Your EVM_PRIVATE_KEY is only used locally to sign payment authorizations — it is never transmitted to any server.
• Payments are processed on-chain via the x402 protocol using a Facilitator.

License

MIT