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 — credentials provided upon registration
  • AGENTRY_ID — your buyer identity ID (e.g. AGT-XXXXX)
  • AGENTRY_API_KEY — your API key (starts with agt_)
• An EVM wallet private key — used to sign x402 payment authorizations (Base Sepolia testnet or mainnet)

Quick Start

Step 1 — Get your credentials

Sign up and obtain your ID and API Key from your account profile.

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

Step 2 — Add to your MCP client

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

{
  "mcpServers": {
    "x402-gateway": {
      "command": "npx",
      "args": ["-y", "@ppgppgppg/mcp-gateway"],
      "env": {
        "EVM_PRIVATE_KEY": "0xYOUR_WALLET_PRIVATE_KEY",
        "AGENTRY_ID": "AGT-XXXXX",
        "AGENTRY_API_KEY": "agt_YOUR_API_KEY"
      }
    }
  }
}

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. | | AGENTRY_ID | ✅ | Your buyer ID (AGT-...). Used for identity and compliance checks. | | AGENTRY_API_KEY | ✅ | Your API key (agt_...). Used to fetch the tool registry and run compliance checks. | | 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 pricing. | | 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 ~/.agentry/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