SQD Portal MCP Server

Thin MCP wrapper around the SQD Portal API for blockchain data queries.

This server does not index chains itself. It validates user input, maps it onto Portal requests, and returns MCP-friendly responses.

The current v0.8.4 release supports the stateless MCP `2026-07-28` protocol over HTTP and stdio, while retaining the SDK-managed legacy negotiation path for clients still rolling out the revision. No SQD account, API key, or client credential is required.

v0.8.4 makes factual completeness a release gate. It verifies requested and actual time bounds, stable row identities, exact page continuation, wallet membership, Bitcoin units, transaction and candle totals, input validation, and response budgets against direct Portal evidence across EVM, Solana, Bitcoin, Substrate, Hyperliquid, and applicable Tron metadata paths. Tool results expose the exact `_server.version`. The SQD Explorer uses the current SQD Design System, retains cached App URIs from supported releases, preserves exact hashes and tiny decimal amounts across every display and export surface, and adds honest App identity, explicit open-bucket state, safe failed-follow-up states, and client-side paging for large evidence tables.

Current public surface

• `25` public tools
• `3` advanced/debug tools
• public params use `network`
• discovery filters use `vm`
• no legacy tool aliases in `v0.8.x`

Raw query tools default to compact responses. Ask for `response_format: "full"` only when you need the larger payload.

Entity questions can use `portal_resolve_entity` first. It resolves EVM token symbols/addresses, EVM contract aliases, pool identifiers, protocol names, and Hyperliquid coin names into query-ready filters while keeping ambiguous matches explicit.

Token symbol resolution and token metadata come from open token-list data, not baked-in token address constants. Responses include explicit notices when token-list data is unavailable, stale, or unsupported for a network.

Wallet questions should start with `portal_get_wallet_summary`. It returns `fund_flow` by default, including inbound/outbound movement, asset flows, counterparties, largest observed movements, and next evidence pivots before raw-tool drill-down.

Tool groups

Discovery:

• `portal_list_networks`
• `portal_get_network_info`
• `portal_get_head`
• `portal_resolve_entity`

Cross-chain convenience:

• `portal_get_recent_activity`
• `portal_get_wallet_summary`
• `portal_get_time_series`

EVM:

• `portal_evm_query_transactions`
• `portal_evm_query_logs`
• `portal_evm_query_token_transfers`
• `portal_evm_get_contract_deployment`
• `portal_evm_get_contract_activity`
• `portal_evm_get_analytics`
• `portal_evm_get_ohlc`

Solana:

• `portal_solana_query_transactions`
• `portal_solana_query_instructions`
• `portal_solana_get_analytics`

Bitcoin:

• `portal_bitcoin_query_transactions`
• `portal_bitcoin_get_analytics`

Substrate:

• `portal_substrate_query_events`
• `portal_substrate_query_calls`
• `portal_substrate_get_analytics`

Hyperliquid:

• `portal_hyperliquid_query_fills`
• `portal_hyperliquid_get_analytics`
• `portal_hyperliquid_get_ohlc`

Advanced/debug:

• `portal_debug_query_blocks`
• `portal_debug_resolve_time_to_block`
• `portal_debug_hyperliquid_query_replica_commands`

Supported data

• EVM networks indexed by Portal, including Base, Ethereum, Optimism, Arbitrum, Monad, Hyperliquid EVM, and many others
• Tron discovery, head, freshness, and timestamp metadata, with native Tron stream queries documented in the bundled SQD plugin skill
• Solana mainnet
• Bitcoin mainnet
• Hyperliquid fills and replica commands
• Substrate networks indexed by Portal

Substrate support is currently historical only. It does not have a real-time tail.

Response shape

Most tools return the same envelope in MCP `structuredContent` and in a compact JSON text fallback for older clients. The envelope contains a normal result body plus shared metadata such as:

• `answer`
• `display`
• `next_steps`
• `investigation`
• `_freshness`
• `_coverage`
• `_pagination`
• `_ordering`

`investigation` is a compact evidence guide for agents: it identifies the primary result path, bounded window, useful pivot fields such as addresses or transaction hashes, follow-up filters, and limitations before a result is treated as complete. Successful material results also carry an `_evidence` receipt with canonical arguments, a deterministic digest, row reconciliation, source windows, and either exact or semantic replay semantics. Exact receipts pin their evidence window. Semantic receipts disclose that rerunning a moving relative window can return a newer snapshot.

When a response uses estimated, partial, sampled, capped, or paginated data, the top-level answer and metadata disclose it. Safe pagination follow-ups include executable tool-call metadata with explicit cursor arguments; suggestions that cannot be reconstructed safely are marked non-executable.

Chart-oriented tools also return chart and table descriptors so MCP clients or LLMs can render them without reverse-engineering the payload.

SQD Explorer is in beta and is off by default. A default deployment answers with `structuredContent` and compact JSON text only, and no tool result asks a host to open a UI. There are two ways to opt in:

• One connection: add `?app=1` to the endpoint, for example `https://portal.sqd.dev/mcp?app=1`. Use this to try the beta without changing anything for other users.
• Whole deployment: set `MCP_APP_ENABLED=true`. A connection can still override it in either direction, so `?app=0` opts a single client back out.

The app resource stays registered either way, so a host can read it directly without anyone opting in.

v0.8.4 includes one portable SQD Explorer for 21 data tools. When it is enabled, compatible MCP App hosts receive linked overview, chart, evidence, and investigation sections; exact metrics, multi-series and signed-value charts, right-scaled price candles with linked volume, tables, timelines, coverage, freshness, and continuation controls; range-focused follow-ups; current-session investigation history; and JSON or CSV export of the received evidence. Pointer and keyboard inspection expose exact plotted values. Large received tables page in 20-row views without discarding evidence. Missing buckets remain visible as gaps, identifiers stay unshortened, and any local row cap is separate from server completeness. Failed calls clear stale success data. The app is self-contained, does not use persistent browser storage, and makes no browser-side network requests. Hosts without MCP App support receive the same `structuredContent` and compact JSON text fallback, so the underlying answer never depends on the UI.

Three MCP prompts provide reproducible starting points without adding tools:

• `investigate-wallet`
• `investigate-contract`
• `investigate-market`

For a chart-first App demo, ask: `Show BTC price action and trading volume on Hyperliquid for the past hour, using five-minute candles. Explain whether the final candle is closed.` The result opens the SQD Explorer with an exact candle chart, volume, an evidence table, requested and indexed time bounds, and a receipt. Replay the returned `requested_window_start_timestamp` and `requested_window_end_exclusive` as fixed `from_timestamp` and `to_timestamp` inputs when you need a stable verification run.

Install

npm install
npm run build

Run

stdio:

npm start

HTTP:

npm run start:http

Developer discovery

The server exposes a structured tool-selection guide for client builders:

• MCP resource `sqd://tools` returns grouped tool metadata, examples, starting points, and integration notes.
• MCP resource `sqd://tools/{name}` returns the guide entry for one tool, for example `sqd://tools/portal_get_time_series`.

Tool and resource discovery stays on the MCP protocol itself. The server does not maintain a duplicate HTTP catalog.

Codex plugin

The Codex plugin wrapper lives in `plugins/portal` and defaults to the hosted MCP endpoint at `https://portal.sqd.dev/mcp`.

Install it from this repo-local marketplace:

codex plugin marketplace add .
codex plugin add portal@sqd

Open a new Codex thread after installing. First-use prompts include Hyperliquid BTC perp fills, recent Base transaction volume, and the latest USDC transfers on Base.

Claude Code plugin

The Claude Code plugin uses the same hosted MCP endpoint and the same public selector:

claude plugin marketplace add subsquid-labs/portal-mcp-server
claude plugin install portal@sqd

Open a new Claude Code session after installing so the SQD MCP tools are loaded.

Grok

Grok chat can use SQD as a custom connector:

1. Open `grok.com/connectors`.

2. Choose New Connector, then Custom.

3. Enter `https://portal.sqd.dev/mcp` as the MCP server URL.

4. Leave authentication unset for the credential-free v0.8.x server.

Grok Build reads Claude Code plugins directly, so it uses the same package rather than a made-up Grok-only manifest:

grok plugin install --trust subsquid-labs/portal-mcp-server#plugins/portal

The v0.8.4 release gate validates the Codex, Claude Code, Grok Build, Gemini CLI, and Cursor packages, then runs the same discovery, prompt, resource, fallback, evidence, continuation, concurrency, and recovery journeys for all five declared client families. It also compares material results with direct Portal evidence and rejects missing or duplicate normalized identities. Real installed-client calls are recorded separately so package validation is never presented as runtime proof.

ChatGPT

In a workspace with custom MCP apps enabled, open Settings → Apps → Create, enter `https://portal.sqd.dev/mcp`, choose no authentication, scan the tools, and create the draft app. The server is read-only and does not require user credentials in v0.8.x.

Claude Desktop

Add an entry like this to `claude_desktop_config.json`:

{
  "mcpServers": {
    "SQD": {
      "command": "node",
      "args": ["/absolute/path/to/sqd-portal-mcp-server/dist/index.js"]
    }
  }
}

Usage notes

• If you do not know the exact network name, start with `portal_list_networks`.
• If you need recent indexed state, use `portal_get_network_info` or `portal_get_head` first.
• If the question is broad, start with `portal_get_recent_activity`, `portal_get_wallet_summary`, or `portal_get_time_series` before dropping to raw queries.
• Time windows accept compact and natural wording such as `30m`, `past 30 minutes`, `in the past 1h`, `in last 38 mins`, `last hour`, or `30 minutes ago`.
• Use `portal_evm_get_ohlc` and `portal_hyperliquid_get_ohlc` only when you actually need candle-shaped output.
• For large or exploratory queries, prefer `response_format: "compact"` unless you need the full record shape.

HTTP Deployment Notes

HTTP mode exposes MCP at `/` and `/mcp`, with local health state at `/health`. The hosted service exposes the same versioned health response at `https://portal.sqd.dev/mcp/health`.

• MCP and health are public in v0.8.x. User authentication is deferred to a unified `auth.sqd.dev` flow in v0.9.0.
• Tool and resource discovery use the MCP protocol; retired `/tools` and `/tools.json` routes return `404`.
• Set `MCP_CURSOR_SECRET` in production so pagination cursors are signed with a deployment-specific secret. Local development uses a deterministic fallback for convenience.

Useful environment variables:

• `MCP_CURSOR_SECRET` to sign pagination cursors
• `MCP_APP_ENABLED` to offer the beta SQD Explorer to compatible hosts, default off. Accepts `true` or `1`. Per-connection `?app=1` and `?app=0` override it.
• `MCP_TOOL_WEIGHT_BUDGET` to bound the combined cost of active tool calls, default `32`. Measured profiles allow up to 32 lookups, 4 raw or summary calls, or 2 analytics calls at once while queued work remains cancellation-aware.
• `MCP_TOOL_MAX_QUEUE` to bound queued tool calls, default `64`
• `MCP_TOOL_QUEUE_TIMEOUT_MS` to bound tool admission wait time, default `5000`

Tests

The release-assurance contract defines the complete v0.8.2 baseline and the additional v0.8.3 and v0.8.4 gates. “100%” refers to every applicable cell in the declared matrix, not a claim that upstream networks can never fail.

npm test
npm run test:protocol
npm run test:tool-admission
npm run test:app-contract
npm run test:app-ui
npm run test:evidence-receipts
npm run test:investigation-prompts
npm run test:investigation-journeys
npm run test:tools
npm run test:routing
npm run test:substrate
npm run test:timestamps
npm run test:plugin
npm run test:claude-plugin
npm run test:grok-plugin
npm run test:conversations
npm run test:negative
npm run test:quality
npm run test:client-journeys
npm run test:ci

License

MIT