@gates-x402/mcp-server

MCP (Model Context Protocol) server for Gates x402 — gives AI agents full control over payment gates, content, analytics, and a built-in Solana wallet with spending safety rails.

Install this single package and your AI agent can manage your entire Gates x402 account, including sending and receiving USDC payments on Solana.

Quick Start

Claude Code

claude mcp add gates-x402 -s user -- npx @gates-x402/mcp-server --stdio

Then set environment variables by adding a .mcp.json to your project root:

{
  "mcpServers": {
    "gates-x402": {
      "command": "npx",
      "args": ["@gates-x402/mcp-server", "--stdio"],
      "env": {
        "GATES_API_KEY": "pg_test_xxx",
        "SOLANA_NETWORK": "mainnet-beta"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "gates-x402": {
      "command": "npx",
      "args": ["@gates-x402/mcp-server", "--stdio"],
      "env": {
        "GATES_API_KEY": "pg_test_xxx",
        "SOLANA_NETWORK": "mainnet-beta"
      }
    }
  }
}

OpenAI Agents SDK

from agents import Agent
from agents.mcp import MCPServerStdio

mcp = MCPServerStdio(
    name="gates-x402",
    command="npx",
    args=["@gates-x402/mcp-server", "--stdio"],
    env={
        "GATES_API_KEY": "pg_test_xxx",
        "SOLANA_NETWORK": "mainnet-beta",
    },
)

agent = Agent(
    name="Payments Agent",
    instructions="You manage payment gates on Gates x402.",
    mcp_servers=[mcp],
)

Programmatic (Node.js)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["@gates-x402/mcp-server", "--stdio"],
  env: {
    GATES_API_KEY: "pg_test_xxx",
    SOLANA_NETWORK: "devnet",
  },
});

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
const result = await client.callTool({ name: "list_paygates", arguments: {} });

Environment Variables

Required

| Variable | Description | |----------|-------------| | GATES_API_KEY | Your Gates x402 API key (pg_test_* for devnet, pg_live_* for mainnet) |

Optional — API

| Variable | Default | Description | |----------|---------|-------------| | GATES_API_URL | http://localhost:4021 | Gates x402 API server URL |

Optional — Wallet

| Variable | Default | Description | |----------|---------|-------------| | WALLET_KEYPAIR_PATH | ~/.gates-x402/wallet.json | Path to Solana keypair JSON file | | WALLET_PRIVATE_KEY | — | Base58-encoded private key (alternative to file path) | | SOLANA_RPC_URL | Solana public RPC | Solana RPC endpoint (Helius, QuickNode, etc.) | | SOLANA_NETWORK | mainnet-beta | mainnet-beta or devnet |

Optional — Safety Rails

| Variable | Default | Description | |----------|---------|-------------| | WALLET_MAX_SOL_PER_TX | 1.0 | Maximum SOL per single transaction | | WALLET_MAX_USDC_PER_TX | 10.0 | Maximum USDC per single transaction | | WALLET_DAILY_USDC_LIMIT | 50.0 | Maximum USDC the agent can spend per day | | WALLET_ALLOWLIST | — | Comma-separated list of allowed recipient addresses. If set, transfers to unlisted addresses are blocked. |

Wallet

The MCP server includes a built-in Solana wallet so your AI agent can hold and transfer SOL and USDC.

Auto-generated on first run

When the server starts for the first time, it automatically generates a new Solana keypair and saves it to ~/.gates-x402/wallet.json (or the path you set in WALLET_KEYPAIR_PATH). You'll see this in the server logs:

[gates-x402] New wallet auto-generated and saved to: /Users/you/.gates-x402/wallet.json
[gates-x402] Public key: 7xKp...abc
[gates-x402] IMPORTANT: Back up this file — it contains your private key.

Persistent across sessions

The wallet is a file on disk — it persists across conversations, server restarts, and reboots. Every time the server starts, it loads the same keypair from the same path. Multiple Claude Code windows or agent sessions share the same wallet.

Back up your keypair

The file at ~/.gates-x402/wallet.json contains your private key. If it's deleted, the wallet and any funds in it are gone forever. Copy it somewhere safe.

Safety rails

The wallet enforces spending limits to prevent runaway agents:

• Per-transaction cap — Blocks any single transfer above the configured maximum (default: 1 SOL / $10 USDC)
• Daily spending limit — Tracks cumulative USDC spent per day (default: $50/day), resets at midnight
• Address allowlist — If WALLET_ALLOWLIST is set, the agent can only send funds to those addresses
• Mainnet warnings — Large transfers on mainnet-beta produce warnings in the tool response
• Devnet airdrop only — The wallet_airdrop tool is disabled on mainnet

All limits are configurable via environment variables (see table above).

Tools (23)

Paygate Management

| Tool | Description | |------|-------------| | list_paygates | List all payment gates with status, pricing, and transaction counts | | create_paygate | Create a new paygate with name, price (USD), resource URL, optional description and webhook | | update_paygate | Update an existing paygate (pass only the fields to change) | | delete_paygate | Permanently delete a paygate |

Analytics

| Tool | Description | |------|-------------| | get_analytics | Revenue data with optional date range and paygate filters |

Content

| Tool | Description | |------|-------------| | list_content | List hosted files for a paygate with sizes and preview URLs | | get_storage_usage | Storage quota, used space, and file count | | upload_content_file | Upload a file from the local filesystem to a paygate (images, video, audio, documents, code) | | upload_content_text | Create and upload text-based content inline (markdown, code, JSON, etc.) |

Billing

| Tool | Description | |------|-------------| | get_billing_summary | Revenue, platform fees, net earnings, and monthly breakdown | | list_transactions | Paginated transaction history |

Subscriptions

| Tool | Description | |------|-------------| | get_subscription | Current tier, usage limits, and expiration date |

Webhooks

| Tool | Description | |------|-------------| | get_webhook_stats | Delivery statistics (success/failure counts) |

API Keys

| Tool | Description | |------|-------------| | list_api_keys | List keys (prefix and last-used only — full keys are never exposed) | | create_api_key | Create a test or live API key (shown once on creation) |

Profile

| Tool | Description | |------|-------------| | get_profile | Creator profile: username, bio, wallet address, social links |

Wallet

| Tool | Description | |------|-------------| | wallet_create | Generate a new keypair, replacing the current wallet (requires confirm: true) | | wallet_get_address | Get the wallet public key and keypair file location | | wallet_get_balance | SOL and USDC balances | | wallet_transfer_sol | Send SOL (subject to per-tx limit) | | wallet_transfer_usdc | Send USDC (subject to per-tx and daily limits, auto-creates recipient token account) | | wallet_airdrop | Request devnet SOL airdrop (max 2 SOL, devnet only) | | wallet_spending_status | View spending limits, daily usage, and safety rail config |

Resources (2)

MCP resources provide live data that agents can read without calling a tool:

| Resource | URI | Description | |----------|-----|-------------| | Paygates | gates-x402://paygates | Live list of all payment gates | | Subscription | gates-x402://subscription | Current subscription status and usage |

Example Prompts

Once the MCP server is connected, you can ask your AI agent things like:

• "Create a paygate called 'Premium API' that charges $0.05 per request"
• "Write a markdown article about Solana and upload it to my paygate"
• "Upload the PDF at ~/docs/whitepaper.pdf to my research paygate"
• "Show me my revenue for the last 7 days"
• "What's my wallet balance?"
• "Send 0.1 SOL to 7xKp...abc"
• "List all my paygates and tell me which ones have the most transactions"
• "Check my subscription tier and storage usage"
• "How much USDC have I spent today?"

Development

# Clone and install
git clone https://github.com/gatesx402/gates-x402.git
cd gates-x402
pnpm install

# Build
pnpm --filter @gates-x402/mcp-server build

# Dev mode (auto-reload)
pnpm --filter @gates-x402/mcp-server dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node ./packages/mcp-server/dist/index.js --stdio

License

MIT