Parallax Protocol

parallax-mcp ============

A Model Context Protocol server that gives AI assistants and agents structured, read-only access to the Parallax network: chain data from a node, indexed data from the explorer, network health from the status page, and the Parallax documentation and PIPs.

It runs locally over stdio (Claude Desktop, Claude Code) or as a remote Streamable HTTP service, and never holds or accepts private keys.

A public instance runs at https://mcp.parallaxprotocol.org/mcp, and the server is listed in the MCP Registry as io.github.ParallaxProtocol/parallax-mcp.

• Tools
• Resources and prompts
• Using it
• Configuration
• Security model
• Deployment
• Development

Tools

Tools are grouped, and each group can be turned off. Every result is compact JSON with LAX amounts as {"wei": "...", "lax": "..."}, and anything third parties can write is wrapped as {"untrusted": "..."} (see Security model).

chain: from the node's JSON-RPC

mining: derived from block headers and the emission schedule; each derivation is documented in the tool description

explorer: from Blockscout's REST API v2

explorer_address, explorer_token_balances, explorer_transactions, explorer_token, explorer_token_holders, explorer_token_transfers, explorer_contract (interface, metadata and optionally source), explorer_internal_transactions, explorer_search, explorer_stats (including the stats service's counters), and explorer_charts: 21 time series (accounts, transactions, fees, blocks, gas, contracts) at day, week, month or year resolution from Blockscout's stats service. Lists are paginated with an opaque next_cursor.

network: from the status page and the node

mempool: mempool_status (node and network-wide) and mempool_transactions (needs txpool).

docs: search_docs ranks the Parallax documentation and PIPs for a question (BM25, boosted by titles and headings) and returns excerpts with links; read_doc returns a page or PIP in full, in parts for long ones. They let assistants look up Parallax specifics on their own instead of guessing from Ethereum or Bitcoin.

tx: off by default

Which tools a node supports

The public RPC endpoint serves only eth, net and web3. Tools that need more (trace_* need debug, node_peers needs admin, mempool_transactions needs txpool) are left out when the node does not serve their namespace; chain_info lists what it does. To get them all, point the server at your own node:

parallaxd --http --http.addr 127.0.0.1 \

--http.api eth,net,web3,txpool,debug,admin,xhash --gcmode archive --txlookuplimit 0

Exposing these namespaces to parallax-mcp is safe: it calls them through an allowlist of read-only methods (see Security model). Do not expose them to anything else. Historical state (balances, calls and traces at old blocks) needs --gcmode archive.

Resources and prompts

Subscriptions work on stdio and on the HTTP transport's sessions (not with --http-stateless). The server polls the node every --head-poll-interval (15 s) only while someone is subscribed or waiting, and stops ten minutes after the last interest. Clients without subscription support can call wait_for_new_block instead.

The documents are a snapshot embedded in the binary, searchable with the docs tools. CI refreshes it from the parallax-docs repository's main branch and the PIP discussions whenever it builds an image, so published images carry current docs; locally, make sync-content does the same from ../parallax-docs (it needs the gh CLI).

Prompts: explain_transaction (hash), audit_address (address), network_health_report.

Using it

Claude Code

Local, over stdio:

claude mcp add parallax -- /path/to/parallax-mcp

with the transaction tools, against your own node:

claude mcp add parallax -- /path/to/parallax-mcp --groups chain,mining,explorer,network,mempool,docs,tx --rpc-url http://127.0.0.1:8545

Remote, over HTTP, using the public instance:

claude mcp add --transport http parallax https://mcp.parallaxprotocol.org/mcp

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config):

{

"mcpServers": { "parallax": { "command": "/path/to/parallax-mcp", "args": ["--log-level", "warn"] } } }

or with Docker:

{

"mcpServers": { "parallax": { "command": "docker", "args": ["run", "-i", "--rm", "ghcr.io/parallaxprotocol/parallax-mcp", "--transport", "stdio"] } } }

A remote HTTP deployment is added in Claude Desktop as a custom connector (Settings → Connectors → Add custom connector) with its URL, such as https://mcp.example.org/mcp.

From a shell

bin/mcpcall (make tools) is a small MCP client for trying tools:

bin/mcpcall tools

bin/mcpcall call get_block '{"block":"latest"}' bin/mcpcall call call_contract '{"to":"0xd1060183552A88455f037a58B2aC639C7966a214","function":"symbol() returns (string)"}' bin/mcpcall read parallax://glossary bin/mcpcall -http http://127.0.0.1:8080/mcp call network_health bin/mcpcall call trace_transaction '{"hash":"0x…"}' -- --rpc-url http://127.0.0.1:8545

Configuration

Settings come from flags, PARALLAX_MCP_* environment variables and an optional YAML file (--config, see config.example.yaml), in that order of precedence. parallax-mcp -help lists them all.

Security model

Untrusted data. Token names and symbols, contract source, event and revert strings, decoded string arguments, explorer tags and node names are chosen by anyone and may be written to manipulate a model reading them. Such text is stripped of control, bidirectional and zero-width characters, capped in length, and wrapped as {"untrusted": "..."}; the server's instructions tell the model to treat it as data only.

Read-only by construction. Every request to the node passes an allowlist of read-only JSON-RPC methods before it leaves the process, so even a node with personal, admin, miner and debug fully exposed cannot be made to unlock ac