subsquid-labs/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.