SQD

SQD Portal MCP Server

An MCP server that answers blockchain questions from SQD Portal data: transactions, logs, traces, token transfers, wallets, analytics, time series, and candles across EVM, Solana, Bitcoin, Substrate, Hyperliquid, and Tron networks, with an optional in-host Explorer.

The server does not index chains itself. It validates input, plans bounded Portal queries, and returns results with coverage, freshness, pagination, and evidence metadata so an assistant can say exactly what it saw. No SQD account, API key, or client credential is required.

It speaks the stateless MCP 2026-07-28 protocol over HTTP and stdio and keeps the SDK-managed legacy negotiation path for clients still rolling out that revision. Release notes are in CHANGELOG.md. See CONTRIBUTING.md to work on the code and SECURITY.md to report a vulnerability.

Current public surface

• 28 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_traces
• 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

Tron:

• portal_tron_query_transactions
• portal_tron_query_logs

Advanced/debug:

• portal_debug_query_blocks
• portal_debug_resolve_time_to_block
• portal_debug_hyperliquid_query_replica_commands

These groups are also the toolsets (discovery, convenience, evm, solana, bitcoin, substrate, hyperliquid, tron, debug). A deployment can trim the catalog with MCP_TOOLSETS or MCP_TOOLS, and an HTTP connection can narrow it further with ?toolsets= or an X-MCP-Toolsets header; see the HTTP deployment notes. With nothing configured the full 31-tool surface is served, and the hosted endpoint keeps that default.

Supported data

• EVM networks indexed by Portal, including Base, Ethereum, Optimism, Arbitrum, Monad, Hyperliquid EVM, and many others
• Tron native transactions (TRX transfers, TRC-10 transfers, contract calls with inline logs and internal transactions) and TVM event logs such as TRC-20 transfers, with Base58 or hex addresses, exact TRX amounts, and the parent transaction hash on every log; the bundled SQD plugin skill documents the raw Stream API for anything beyond that
• 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. _pagination.has_more is true exactly when next_cursor is present, and _coverage states whether the requested window was read through (window_complete) and whether the response holds every matching row (result_complete). 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 (beta)

SQD Explorer is an MCP App that renders tool results inside hosts that support MCP Apps. It is in beta and 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.

When it is enabled, compatible hosts receive an inline card sized to its content and a full-screen workspace for 21 data tools: metrics led by the primary number, multi-series and signed-value charts, price candles with linked volume and a fixed readout, ranked and timeline panels that show ten rows with a Show all control, evidence tables that page ten rows with search across every row, explorer links for addresses, hashes, and blocks, chain logos and names from SQD network metadata, continuation controls, current-session history, and JSON or CSV export through the host. Pointer and keyboard inspection expose exact plotted values. Missing buckets remain visible as gaps, identifiers stay unshortened, and any local row cap is separate from server completeness. Failed follow-ups keep the last good result under the error. The app is self-contained and does not use persistent browser storage; its only browser-side requests are chain logo images from cdn.subsquid.io and sqd.dev, the two origins declared in the resource CSP. Hosts without MCP App support receive the same structuredContent and compact JSON text fallback, so the underlying answer never depends on the UI. docs/explorer-design.md records the design rules the app follows.

Three MCP prompts provide reproducible starting points without adding tools:

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

For a chart-first 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 a 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.

Try it in Claude

The hosted endpoint has the Explorer off, so a new user opts their own connection in:

1. In claude.ai or Claude Desktop, open Settings → Connectors → Add custom connector, enter https://portal.sqd.dev/mcp?app=1, and choose no authentication. The ?app=1 turns the beta on for this connection only. On Claude Desktop you can instead install sqd.mcpb from the latest release and switch on its "SQD Explorer (beta)" setting.
2. Start a new chat and enable the SQD connector for it.
3. Ask a data question. Any of these lands on a tool that carries the Explorer:

• What has this wallet been doing on Base lately? with an address (wallet summary)
• Show me recent activity on Ethereum (recent activity)
• Chart hourly transaction counts on Base for the last day (time series)

The result renders as an inline card instead of a block of text; open the card for the full-screen workspace. Only the 21 data tools carry the Explorer. A catalogue question such as Which networks do you support? calls portal_list_networks and answers in plain text, which is expected rather than a failure.

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.

Grok Build reads Claude Code plugins directly, so it uses the same package:

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

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.

Claude Desktop

Download sqd.mcpb from the latest release and open it: Claude Desktop installs the bundle with one click and lists the 31 tools. The bundle carries the server, its production dependencies, and one optional setting, "SQD Explorer (beta)", which is off by default. It needs Node 22 or n