parallax-mcp

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

A [Model Context Protocol](https://modelcontextprotocol.io) 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](https://explorer.parallaxprotocol.org), network health from the
[status page](https://status.parallaxprotocol.org), 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](https://registry.modelcontextprotocol.io)
as `io.github.ParallaxProtocol/parallax-mcp`.

- [Tools](#tools)
- [Resources and prompts](#resources-and-prompts)
- [Using it](#using-it)
- [Configuration](#configuration)
- [Security model](#security-model)
- [Deployment](#deployment)
- [Development](#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](#security-model)).

**chain**: from the node's JSON-RPC

| Tool | What it returns |
|---|---|
| `chain_info` | Chain ID check, client, head and its age, sync state, peers, gas price, the node's RPC namespaces |
| `get_block` | A block by number, hash or `latest`, with block time, subsidy and optionally transaction summaries |
| `get_transaction` | A transaction with its calldata decoded (verified ABI from the explorer, or the standard token ABI) |
| `get_receipt` | Status, gas used, fee and decoded event logs |
| `get_balance` | Balance and nonce, at any block on an archive node |
| `get_code`, `get_storage_at`, `get_proof` | Bytecode, storage slots and EIP-1186 proofs |
| `call_contract` | A read-only `eth_call`, encoding arguments and decoding results from an ABI, the explorer's verified ABI or a signature such as `balanceOf(address) returns (uint256)` |
| `estimate_gas` | Gas and fee for a transaction |
| `get_logs` | Event logs, bounded by block range and count |
| `gas_price` | `eth_gasPrice` and Parallax's Bitcoin Core-style fee estimates for 1 to 144 blocks |
| `audit_token_approvals` | Every ERC-20 allowance and NFT approval an address has granted that is still live, checked against current contract state, with exposure, risk flags, severity and the exact revoke call |
| `wait_for_new_block` | Waits (up to 10 minutes) for the next block; for clients without resource subscriptions |
| `trace_transaction`, `trace_call` | Call trees, pre-state and selectors (needs the `debug` namespace) |

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

| Tool | What it returns |
|---|---|
| `mining_stats` | Block time statistics, hashrate estimate, difficulty and its trend, expected block time, miner shares, and the status page's figures for comparison |
| `supply_info` | Issued supply (node and schedule cross-checked), share of the 21M cap, current reward and era, next halving at the target and observed pace |
| `block_reward` | A block's subsidy plus fees, and when it matures |

**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

| Tool | What it returns |
|---|---|
| `network_health` | One report: alerts, ongoing incidents, mining decentralization and recommended confirmations, nodes, propagation, reorgs, mempool, and the node's own head, peers and sync state, with a list of issues |
| `network_nodes` | The nodes reporting to the status page |
| `network_incidents` | Incident history and verified nodes' uptime |
| `network_propagation` | Block propagation delays, stale blocks and reorgs |
| `network_trends` | Hashrate, difficulty, block time, hashprice, security budget, nodes, latency, uptime and mempool over 7 days in 4-hour slices |
| `node_peers` | The node's peers and address book, with IP addresses withheld (needs `admin`) |

**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

| Tool | What it returns |
|---|---|
| `build_unsigned_tx` | An unsigned legacy or EIP-2930 transaction with nonce, gas and gas price filled in, its signing payload and hash, for an external signer |
| `decode_tx` | Any raw transaction or signing payload, decoded, with the sender recovered from the signature |
| `broadcast_signed_tx` | Submits a signed transaction. Registered only with `--allow-broadcast` |

### 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:

```sh
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](#security-model)).
Do not expose them to anything else. Historical state (balances, calls and
traces at old blocks) needs `--gcmode archive`.

## Resources and prompts

| Resource | Content |
|---|---|
| `parallax://chain/parameters` | Chain ID, block time, PoW and ASERT, reward schedule and cap, coinbase maturity, EVM level (Berlin) and transaction types, endpoints |
| `parallax://glossary` | Parallax and proof-of-work terms used by the tools |
| `parallax://docs`, `parallax://docs/{path}` | The documentation of [docs.parallaxprotocol.org](https://docs.parallaxprotocol.org) (v2.1.x) |
| `parallax://pips`, `parallax://pips/pip-000N` | PIP-0002 to PIP-0006 |
| `parallax://chain/head` | The latest block; **subscribable**: a `resources/updated` notification on every new block (and reorg) |
| `parallax://network/alerts` | The status page's active alerts; **subscribable**: a notification when one appears, clears or changes level |

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` 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` (it needs the `gh` CLI).

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

## Using it

### Claude Code

Local, over stdio:

```sh
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:

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

### Claude Desktop

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

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

or with Docker:

```json
{
  "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:

```sh
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](config.example.yaml)),
in that order of precedence. `parallax-mcp -help` lists them all.

| Flag | Default | |
|---|---|---|
| `--transport` | `stdio` | `stdio` or `http` |
| `--rpc-url` | `https://rpc.parallaxprotocol.org` | Node JSON-RPC (http/https) |
| `--explorer-url` | `https://explorer.parallaxprotocol.org` | Blockscout |
| `--status-url` | `https://status.parallaxprotocol.org` | Status page |
| `--chain-id` | `2110` | The server refuses to start against another chain |
| `--groups` | `chain,mining,explorer,netw