paidmcp-client

paidmcp-client is a local stdio MCP proxy for paid MCP servers that use x402.

It sits between your MCP client (Cursor or Claude Desktop) and a remote paid MCP endpoint, then handles payment negotiation and settlement automatically on each paid tool call.

Requirements

• Node.js 20+
• npm

Install

Use one of these options:

# run without installing globally
npx paidmcp-client --help

# or install globally
npm install -g paidmcp-client

After global install, use the paidmcp command directly:

paidmcp --help

Quick start

1. Create a local payer wallet:

npx paidmcp-client init

This creates ~/.paidmcp/config.json with:

• your seed phrase
• RPC URLs for Base and Plasma
• token addresses for USDC (Base) and USDT0 (Plasma)

2. Check wallet address and balances:

npx paidmcp-client wallet

3. Fund the wallet with USDC on Base or USDT0 on Plasma.

4. Connect to your paid MCP endpoint:

npx paidmcp-client connect https://your-mcp-host.dev

5. Add the printed snippet to your MCP client config (Cursor or Claude Desktop).

CLI commands

npx paidmcp-client init
npx paidmcp-client wallet
npx paidmcp-client connect <endpoint>
npx paidmcp-client run <endpoint>

Examples:

npx paidmcp-client connect http://localhost:4021
npx paidmcp-client run https://your-mcp-host.dev

Configure Cursor or Claude Desktop

Generate a config snippet for a paid MCP endpoint:

npx paidmcp-client connect https://your-mcp-host.dev

The command prints JSON like:

{
  "mcpServers": {
    "your-mcp-host-dev": {
      "command": "node",
      "args": ["/path/to/paidmcp-client/dist/cli.js", "run", "https://your-mcp-host.dev"]
    }
  }
}

Paste this into your MCP config file and restart your MCP client if needed.

Local development (from source)

Inside client/:

npm install
npm run build

Run commands from source:

npm run init
npm run wallet
npm run connect -- http://localhost:4021
npm run run -- http://localhost:4021

With MCP Inspector:

npx @modelcontextprotocol/inspector node dist/cli.js run http://localhost:4021

Troubleshooting

paidmcp: command not found

Use one of:

• npx paidmcp-client <command>
• npm install -g paidmcp-client then paidmcp <command>
• from source: npm run <script>

Missing config error

If you see an error like Run "paidmcp init" first, create the local config:

npx paidmcp-client init

No balance / payment failure

• verify your wallet has funded USDC (Base) or USDT0 (Plasma)
• verify endpoint URL and network availability
• run npx paidmcp-client wallet to confirm balances are readable

Security notes

• ~/.paidmcp/config.json contains your seed phrase in plaintext.
• Never commit or share this file.
• Back up your seed phrase securely. Losing it means losing access to funds.

License

MIT. See LICENSE.