@gates-x402/mcp-server

MCP Server for AI Agents

Give your AI agent full control over payment gates, content, analytics, and a built-in Solana wallet with spending safety rails. One package, 23 tools.

Quick Start

Claude Code

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

Then add a .mcp.json to your project root with your API key:

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

Cursor

.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

Python
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)

TypeScript
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

VariableDescription
GATES_API_KEYYour API key (pg_test_* for devnet, pg_live_* for mainnet)

Optional

VariableDefaultDescription
GATES_API_URLlocalhost:4021Gates x402 API server URL
WALLET_KEYPAIR_PATH~/.gates-x402/wallet.jsonPath to Solana keypair JSON file
WALLET_PRIVATE_KEYBase58-encoded private key (alternative to file)
SOLANA_RPC_URLSolana public RPCSolana RPC endpoint (Helius, QuickNode, etc.)
SOLANA_NETWORKmainnet-betamainnet-beta or devnet

Safety Rails

VariableDefaultDescription
WALLET_MAX_SOL_PER_TX1.0Maximum SOL per single transaction
WALLET_MAX_USDC_PER_TX10.0Maximum USDC per single transaction
WALLET_DAILY_USDC_LIMIT50.0Maximum USDC the agent can spend per day
WALLET_ALLOWLISTComma-separated allowed recipient addresses

Built-in 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

A new Solana keypair is automatically generated and saved to ~/.gates-x402/wallet.json on first start. The same wallet is loaded on every subsequent run.

Persistent across sessions

The wallet is stored on disk — it persists across conversations, server restarts, and reboots. Multiple agent sessions share the same wallet.

Safety rails

  • Per-transaction cap — Blocks transfers above the configured maximum (default: 1 SOL / $10 USDC)
  • Daily spending limit — Tracks cumulative USDC spent per day (default: $50/day)
  • Address allowlist — Restrict transfers to specific addresses only
  • Mainnet warnings — Large transfers on mainnet produce warnings
  • Devnet airdrop only — Airdrop tool is disabled on mainnet

Tools (23)

Paygate Management

ToolDescription
list_paygatesList all payment gates with status, pricing, and transaction counts
create_paygateCreate a new paygate with name, price, resource URL, optional description and webhook
update_paygateUpdate an existing paygate (pass only the fields to change)
delete_paygatePermanently delete a paygate

Content

ToolDescription
list_contentList hosted files for a paygate with sizes and preview URLs
get_storage_usageStorage quota, used space, and file count
upload_content_fileUpload a file from the local filesystem to a paygate
upload_content_textCreate and upload text-based content inline (markdown, code, JSON, etc.)

Analytics & Billing

ToolDescription
get_analyticsRevenue data with optional date range and paygate filters
get_billing_summaryRevenue, platform fees, net earnings, and monthly breakdown
list_transactionsPaginated transaction history
get_subscriptionCurrent tier, usage limits, and expiration date
get_webhook_statsWebhook delivery statistics (success/failure counts)

API Keys & Profile

ToolDescription
list_api_keysList keys (prefix and last-used only — full keys are never exposed)
create_api_keyCreate a test or live API key (shown once on creation)
get_profileCreator profile: username, bio, wallet address, social links

Wallet

ToolDescription
wallet_createGenerate a new keypair, replacing the current wallet (requires confirm: true)
wallet_get_addressGet the wallet public key and keypair file location
wallet_get_balanceSOL and USDC balances
wallet_transfer_solSend SOL (subject to per-tx limit)
wallet_transfer_usdcSend USDC (subject to per-tx and daily limits)
wallet_airdropRequest devnet SOL airdrop (max 2 SOL, devnet only)
wallet_spending_statusView spending limits, daily usage, and safety rail config

Resources

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

ResourceURIDescription
Paygatesgates-x402://paygatesLive list of all payment gates
Subscriptiongates-x402://subscriptionCurrent subscription status and usage

Example Prompts

Once 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"
"How much USDC have I spent today?"

Get Started

Install with a single command:

npx @gates-x402/mcp-server --stdio

Need an API key? Create an account, subscribe to a plan and generate one in Settings.