circuit-mcp

Give any AI agent Circuit's real-time Solana data and agent-swarm intelligence as tools — auto-paid per call in CIRC over x402. No API keys, no signup. Add it to Claude Desktop, Claude Code, or any agent runtime with one line.

Website · Data API · Circuit SDK · Telegram · X / Twitter

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 data tools (14 free) + dllm_chat (decentralized LLM inference) + pay_settle, 3 guided prompts, and 5 free ambient resources. Every tool is read-only.

Related MCP server: @portalsprotocol/mcp-server

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 — and paid tools return an x402 quote you can pay from your own wallet and complete with pay_settle (see pass-through).

Tools

Free — price & market data

Free — swarm intelligence ⭐ (the differentiator)

Paid (auto-paid in CIRC via x402)

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

Paid — decentralized inference

dllm_chat pays per call in CIRC — the same x402 rail as the data tools, not model credits. Pass prompt (single turn, optional system) or full OpenAI-style messages. The result includes a backend field: mesh = the decentralized DLLM, openrouter-fallback = a hosted fallback model served while the mesh is offline (so a paid call never dead-ends). Point it elsewhere with CIRCUIT_INFERENCE_URL (default https://inference.circuitllm.xyz).

Settlement — pay_settle: when the server has no wallet, a paid tool returns an x402 quote instead of paying. Pay it on Solana yourself (CIRC to the recipient, or any registered token to its collector), then call pay_settle with the same { tool, args } and your transaction signature to get the data. With a funded CIRCUIT_WALLET, paid tools auto-pay and you never need this.

Prompts

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

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.

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.

Pass-through (no wallet). Without CIRCUIT_WALLET, the server doesn't pay — it returns that 402 quote to the caller. You pay it yourself and finish with pay_settle; the data API verifies the signature on-chain (single-use, ≤5 min), so the server never holds funds. This is how a wallet-free hosted endpoint (like mcp.circuitllm.xyz) lets each caller pay per call in their own token. For a Circuit-fronted hosted deployment, 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.