Beta software. circuit-mcp is under active development — expect breaking changes, incomplete features, and rough edges. Paid tools spend real CIRC per call; start with the free tools (or a small spend cap) until you're comfortable with how it behaves.

What it does

A thin Model Context Protocol server over @circuit-llm/data. It exposes Circuit's real-time Solana data as tools any MCP client can call — and auto-pays for them per call in CIRC over x402. Free tools return data directly; paid tools are auto-paid from your wallet, bounded per call and per session. No API keys, no accounts.

The differentiator is the swarm_* tools: live signals, consensus, leaderboard, holdings, and a crowd-sourced rug blacklist from Circuit's running trading-agent fleet — data no generic price API has.

29 tools (14 free), 3 guided prompts, and 5 free ambient resources. Every tool is read-only.

Quick Start

Add it to any MCP client (Claude Desktop, Claude Code, an agent runtime):

// claude_desktop_config.json → "mcpServers"
{ "circuit": { "command": "npx", "args": ["-y", "@circuit-llm/mcp"],
    "env": { "CIRCUIT_WALLET": "<base58 secret funded with CIRC>" } } }   // omit → free tools only

Then ask your agent "what's the swarm's consensus on this mint?" or "audit this token for rug risk." The paid tools settle on Solana in ~400ms behind the scenes. Without CIRCUIT_WALLET, the free tools still work.

Tools

Free — price & market data

Tool	What
circuit_quote	live price list for every tool (call this first)
token_price	aggregated USD price (Jupiter + DexScreener + CoinGecko)
live_prices	sub-second batch prices (≤20 mints) from the gRPC indexer
sol_price	current SOL/USD oracle price
token_candles	OHLCV candlesticks (1m/5m/1h/1d) from the on-chain feed
scan	on-chain dip-reversal scanner
slippage_buy / slippage_sell	pre-trade price-impact estimate
x402_accepted_tokens	tokens accepted to pay Circuit's x402 endpoints (universal adapter)

Free — swarm intelligence ⭐ (the differentiator)

Tool	What
swarm_leaderboard ⭐	agents ranked by reputation — whose signals to trust
swarm_holdings ⭐	what the fleet is holding right now (live smart-money positioning)
swarm_blacklist ⭐	crowd-sourced rug/scam avoid-list with reasons
swarm_blacklist_check ⭐	fast single-token "is this flagged?" check
swarm_stats ⭐	live fleet activity + signal volume

Paid (auto-paid in CIRC via x402)

Tool	Cost	What
swarm_feed ⭐	~$0.002	live buy/sell/rug signals from the swarm
swarm_consensus ⭐	~$0.002	reputation-weighted swarm view on one token
swarm_insights ⭐	~$0.002	aggregated patterns the swarm is seeing
token_security	~$0.003	rug-risk audit — authorities, LP lock, risk flags
token_overview	~$0.003	price + metadata + security + pools in one call
token_info	~$0.005	metadata + market data (supply, mcap, FDV, liquidity)
token_holders	~$0.005	holder count + top-5/10/20 concentration
token_top_traders	~$0.005	top traders by volume (Birdeye) — wallet, whale tags, buy/sell, USD volume
trending	~$0.002	trending tokens across sources
new_tokens	~$0.002	freshly launched tokens (discovery feed)
wallet_pnl	~$0.01	realized/unrealized P&L for any wallet
wallet_analytics	~$0.01	behavioral profile — win rate, hold times, sizing
market_regime	~$0.002	risk-on/risk-off macro read
market_sentiment	~$0.002	fear/greed gauge
market_overview	~$0.002	broad market snapshot + top movers

Prices are live from circuit_quote (/api/quote); a few paid endpoints are intermittently ungated (free).

Prompts

Guided workflows that chain the right tools for a single intent:

Prompt	Args	What it does
rug_check	mint	blacklist + security + holders + consensus → SAFE / CAUTION / AVOID
ape_check	mint, solAmount?	consensus + security + slippage + regime → GO / NO-GO
swarm_pulse	—	stats + holdings + leaderboard + fresh buy signals → what the fleet is doing

Resources

Free, read-only ambient context a client can pull without a tool call: circuit://quote, circuit://swarm/leaderboard, circuit://swarm/holdings, circuit://swarm/blacklist, circuit://x402/accepted-tokens.

Configuration

All configuration is via environment variables.

Variable	Default	Purpose
CIRCUIT_WALLET	—	base58 secret key that funds micropayments (omit → free tools only)
CIRCUIT_MCP_MAX_SPEND_CIRC	1000	per-call CIRC spend cap
CIRCUIT_MCP_MAX_TOTAL_CIRC	50000	per-process CIRC cap — the runaway-spend guard; paid tools stop once reached
CIRCUIT_MCP_TIMEOUT_MS	120000	outer per-tool-call backstop (a genuinely stuck call returns a clean error)
CIRCUIT_TREASURY	—	if set, only ever pay this address (recipient allow-list — recommended)
CIRCUIT_DATA_URL	https://api.circuitllm.xyz	override the data API base
CIRCUIT_RPC_URL	public RPC	Solana RPC used to send payments — set your own; the public default rate-limits
CIRCUIT_PAYMENT_MINT	—	pay in a registered token instead of CIRC (see Paying in another token)
CIRCUIT_MCP_MAX_PAYTOKEN	—	required with CIRCUIT_PAYMENT_MINT: per-call ceiling in the token's own base units (fail-closed)
CIRCUIT_MCP_MAX_TOTAL_PAYTOKEN	—	optional cumulative foreign-token ceiling (base units) — the drain guard

Paying in another token

Circuit's Universal x402 Adapter lets any registered token pay Circuit's x402 endpoints — the token is swapped to CIRC on the back end. To have this server pay for tools in a registered token instead of CIRC, set CIRCUIT_PAYMENT_MINT to that mint (call x402_accepted_tokens to see what's registered) and CIRCUIT_MCP_MAX_PAYTOKEN to a per-call ceiling in the token's base units. The ceiling is mandatory — without it the server fails closed and keeps paying CIRC. Any endpoint that doesn't accept the token also falls back to CIRC automatically. Requires a funded CIRCUIT_WALLET that holds the token.

Safety

• Spend is bounded two ways — CIRCUIT_MCP_MAX_SPEND_CIRC per call and CIRCUIT_MCP_MAX_TOTAL_CIRC per process (the drain guard against a looping agent). Set CIRCUIT_TREASURY to pin the payee so a hostile endpoint can't redirect funds.
• Read-only — every tool is a data fetch; none move funds beyond the micropayment.
• No bypass — this package always pays per call; the internal-key bypass is a Circuit-hosted concern, never a user knob (see docs/HOSTING.md).
• Protocol-safe — all logs go to stderr; stdout is reserved for the MCP channel.

How it works

Each paid tool call hits the Circuit Data API: a free endpoint returns data; a paid one answers 402 Payment Required with a CIRC quote. @circuit-llm/data pays the quote from your wallet on Solana and retries — the spend caps and CIRCUIT_TREASURY allow-list bound where and how much. For a hosted deployment (Circuit fronts payment so agents need no wallet), see docs/HOSTING.md.

Develop

git clone https://github.com/Circuit-LLM/MCP && cd MCP
npm install
npm run smoke    # spawn the server via a real MCP client, list tools, exercise the free tools (no spend)
npm start        # run the server over stdio

Built on @circuit-llm/data + @circuit-llm/wallet + the MCP TypeScript SDK.

Part of the Circuit Stack

• circuit-mcp — this repo, Circuit data + swarm intel as x402-paid MCP tools
• circuit-sdk — the TypeScript SDK (x402 · data · wallet · agent · inference)
• circuit-data-api — the x402-gated Solana data aggregator these tools serve
• circuit-agent — the autonomous trading agent behind swarm_feed
• circuitllm.xyz — website and data terminal

---

License

MIT — see LICENSE.