npm package: @ppgppgppg/mcp-gateway
Description: MCP Gateway — connect any AI agent to paid APIs with automatic x402 crypto payments and compliance checks
Latest version: 1.0.3

# x402 MCP Payment Gateway

Connect any MCP-compatible AI agent (Cursor, Claude Desktop, and more) to paid APIs — with automatic [x402](https://x402.org) 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:

```json
{
  "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](https://x402.org) using a Facilitator.

---

## License

MIT