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"]
    }
  }
}

What You Get

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

| Tool | Cost | What it does | |------|------|-------------| | signal402_setup | Free | Create a wallet to pay for x402 services | | signal402_catalog | $0.01 | Browse the full x402 ecosystem | | signal402_recommend | $0.02 | Get ranked service recommendations for a task | | signal402_assess | $0.03 | Deep assessment of a specific x402 project | | signal402_probe | $0.01 | Check if a service is alive and accepting payments | | signal402_call | Varies | Call any x402 service with automatic payment |

Quick Start

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

signal402_setup email="[email protected]"

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:

| You want to... | Use | Why | |-----------------|-----|-----| | Find a service for a task | signal402_recommend | Natural language input, returns ranked matches with scores and explanations | | Browse what exists | signal402_catalog | Full ecosystem view with filters (category, status, sort) | | Evaluate a specific service | signal402_assess | Deep dive: verdict, confidence, pricing analysis, alternatives | | Check if a service is alive | signal402_probe | Real-time health check + .well-known/x402 endpoint discovery | | Call a paid API | signal402_call | Handles the full x402 payment flow -- your wallet pays the service directly | | Set up or check your wallet | signal402_setup | Creates wallet, sponsors gas, shows balance and funding options |

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