signal402-mcp

MCP server for x402 ecosystem intelligence. Discover, evaluate, and call any x402 API service with automatic payment.

Works with Claude Code, Claude Desktop, and any MCP-compatible client.

Full docs and service browsing at signal402.com.

Install

# Claude Code (one command)
claude mcp add signal402 -- npx signal402-mcp

# Or add to .claude.json / claude_desktop_config.json
{
  "mcpServers": {
    "signal402": {
      "command": "npx",
      "args": ["signal402-mcp"]
    }
  }
}

Related MCP server: x402-discovery

What You Get

6 tools that give any AI agent access to the x402 paid API ecosystem:

Quick Start

1. Set Up a Wallet (free, one-time)

signal402_setup email="you@example.com"

This creates a wallet on Base and sponsors initial gas. The email makes it recoverable -- you can restore access on any machine.

Without email (faster but not recoverable):

signal402_setup

2. Fund Your Wallet

Send USDC on Base to the address from setup. Three options:

• From Coinbase: The setup output includes a direct Coinbase Pay link

• From any wallet: Send USDC on Base to your address

• Bridge from another chain: Use jumper.exchange to bridge USDC to Base

Minimum recommended: $1.00 (enough for 50 recommend queries or 100 catalog queries).

3. Discover Services

# "What x402 services can scrape websites?"
signal402_recommend need="web scraping" max_price=0.01

# Browse the full AI category
signal402_catalog category="ai" status="live"

# Is Firecrawl alive right now?
signal402_probe name="firecrawl"

4. Call a Service

# Call a service directly -- payment is automatic
signal402_call url="https://api.firecrawl.dev/v1/scrape" \
  method="POST" \
  body='{"url":"https://example.com"}' \
  max_cost=0.01

5. Deep Dive

# Get an editorial assessment of a service
signal402_assess name="Firecrawl"

# Assess by URL
signal402_assess url="https://firecrawl.dev"

When to Use Each Tool

Use this decision guide to pick the right tool:

Typical workflow:

recommend (find it) --> probe (verify it's alive) --> call (use it)

Or if you already know the service:

probe (check it) --> call (use it)

How Payment Works

• Discovery tools (catalog, recommend, assess, probe): Your wallet pays Signal402 via x402. Costs $0.01-$0.03 per query.

• signal402_call: Your wallet pays the target service directly. Signal402 is not in the payment path. The service sets its own price.

• Spending guard: max_cost (default $0.10) rejects services that charge more than you expect. Override per-call when needed.

All payments use USDC via the x402 protocol. Supports EIP-3009 (TransferWithAuthorization) and Permit2 on any EVM chain (Base, Ethereum, Optimism, Arbitrum, Polygon).

Built on the official @x402/fetch SDK for protocol-compliant payment handling (v1 + v2).

Troubleshooting

"No wallet configured"

Run signal402_setup first. If you previously set up a wallet and it's not found, check that ~/.signal402/wallet.json exists. Re-running setup with the same email recovers the same wallet.

"Insufficient USDC balance" or payments failing

Your wallet needs USDC on Base (chain ID 8453). Common issues:

• USDC on the wrong chain: If you sent USDC on Ethereum mainnet, Arbitrum, or Polygon, it will not work. Bridge to Base using jumper.exchange or send USDC specifically on the Base network.

• Not enough USDC: Check your balance with signal402_setup (it shows current balance). The minimum useful amount is about $0.10.

• ETH for gas: Your wallet needs a small amount of ETH on Base for gas fees. The setup command sponsors initial gas automatically, but if you have been using the wallet heavily, you may need more. Send ~$0.50 of ETH on Base to your wallet address.

"Service not found" from probe or assess

• Check spelling. Probe uses slug-style matching (e.g., firecrawl, not Firecrawl).

• The service may not be in the Signal402 catalog. Use signal402_catalog to browse what is available, or search by URL: signal402_assess url="https://theservice.com".

• Browse the full directory at signal402.com/services.

"max_cost exceeded" from signal402_call

The default spending cap is $0.10 per request. If the service charges more, increase it:

signal402_call url="..." max_cost=0.50

This is a safety feature to prevent accidentally paying more than expected.

x402 payment rejected by a service

• The service may be down or not accepting payments. Run signal402_probe to check.

• Some services only support x402 v1 or v2 -- the SDK handles both, but edge cases exist.

• Ensure your wallet has both USDC (for the payment) and ETH (for gas) on Base.

MCP server not loading

Verify the server is connected:

claude mcp list

If signal402 does not appear, re-add it:

claude mcp add signal402 -- npx signal402-mcp

If using claude_desktop_config.json, restart Claude Desktop after editing the config.

Requirements

• Node.js >= 18

• A funded wallet (USDC on Base recommended)

Links

• Service directory: signal402.com

• Browse services: signal402.com/services

• Register a service: signal402.com/register

• x402 protocol: x402.org

• npm: signal402-mcp

• GitHub: github.com/bflynn4141/signal402