Speccy x402 MCP

@speccy-agent/x402-mcp

MCP server wrapping Speccy's paid x402 endpoints. Give any MCP-compatible AI agent five superpower tools — prediction-market data, a sandboxed Python executor, FFmpeg media transforms, real-time web search, and multilingual text-to-speech — and the server pays per call in USDC on Base on your behalf.

No x402 knowledge required by the agent. No wallet setup on the agent side. Just install the server, point your agent at it, done.

Tools

Tool	Description	Cost per call
get_prediction_markets	Top Polymarket prediction markets (volume, liquidity, or startDate sort)	$0.01 USDC
exec_python	Run Python 3.12 code in an isolated Docker sandbox (no network, read-only FS, 30s timeout, 64KB output)	$0.02 USDC
transform_media	Run FFmpeg on a video/audio file (3 tiers: copy $0.005, transform $0.05, heavy $0.20)	$0.005–$0.20 USDC
web_search	Real-time web search + extract via Tavily (3 modes: search $0.005, extract $0.02, smart search+extract $0.05)	$0.005–$0.05 USDC
tts_synthesize	Multilingual text-to-speech via Supertonic 3 (31 languages, 10 voices, 44.1 kHz WAV). tts tier (≤200 chars) and tts-long tier (≤5000 chars, auto-chunked)	$0.005–$0.02 USDC

Install

npm install -g @speccy-agent/x402-mcp

Configure

Set the operator wallet key (the wallet that pays x402 per call):

export SPECCY_MCP_WALLET_KEY="0x..."   # operator wallet private key

Optional overrides:

• SPECCY_MCP_API_BASE (default https://api.speccy.cloud) — Polymarket endpoint
• SPECCY_MCP_EXEC_BASE (default https://exec.speccy.cloud) — sandbox exec endpoint
• SPECCY_MCP_AUDIO_BASE (default https://audio.speccy.cloud) — Supertonic TTS endpoint

Wire into an MCP-compatible agent

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "speccy-x402": {
      "command": "speccy-x402-mcp",
      "env": { "SPECCY_MCP_WALLET_KEY": "0x..." }
    }
  }
}

Any MCP client (stdio):

SPECCY_MCP_WALLET_KEY=0x... speccy-x402-mcp

Architecture

[Agent] → MCP tool call (stdio) → [this server] → x402 paid fetch → [Speccy endpoint on VPS]
                                                                → [CDP facilitator] → on-chain USDC transfer

The server holds one operator wallet. Each call triggers an x402 payment from that wallet. Settlement alerts go to the operator's Telegram via the Notifier bot (same backend as the HTTP endpoints).

Notes

• The wallet key never leaves the operator's machine (env var, not a config file).
• Fund the wallet with USDC on Base mainnet (eip155:8453) and a tiny amount of ETH for margin (only used if the wallet ever does non-x402 transfers).
• Currently settles on Base mainnet only. Testnet / other chains would need an X402_NETWORK env and a matching facilitator.
• Each call is independent and stateless — no sessions, no state on the server.

Source / issues

• Source: github.com/speccy-ai/x402-mcp (placeholder)
• Issues / feature requests: open an issue on the repo, or message @SpeccyNotifierbot on Telegram

License

MIT — by Philip (Esla) for Speccy.