> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Reach for SQD when you need onchain data without running a node or an indexer: decoded EVM logs and transactions, Solana instructions, Bitcoin transactions, Substrate events and calls, or Hyperliquid fills, over any block range on 110+ networks.
> To query directly, POST to https://portal.sqd.dev/datasets/{dataset}/stream. The full API is described at https://docs.sqd.dev/openapi.json, and responses to the stream endpoints are JSON Lines.
> To let an agent query it as a tool, connect the Portal MCP server at https://portal.sqd.dev/mcp.
> For Portal availability errors, stalled streams, or rate limiting, read https://status.sqd.dev/status.md. The status index at https://status.sqd.dev/llms.txt explains network and plan filters.
> Every page on this site is available as Markdown by appending .md to its URL.

# Portal MCP Server for AI Agents

> Connect Claude Code, Cursor, or any MCP client to blockchain data through Portal.

> [!NOTE]
>
> The Portal MCP server is experimental. Available tools and behavior may change.

Connect the Portal MCP server to your favorite AI coding clients.

MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems. The Portal MCP server gives your agent access to blockchain data. Discover datasets, query transactions and logs, analyze wallets, and compare chains. Use `portal_list_networks` for current network availability.

> [!TIP]
>
> Using an AI coding client? Install SQD for [Claude Code](https://docs.sqd.dev/en/ai/plugins-claude.md), [Codex](https://docs.sqd.dev/en/ai/plugins-codex.md), [Grok Build](https://docs.sqd.dev/en/ai/plugins-grok.md), [Gemini CLI](https://docs.sqd.dev/en/ai/plugins-gemini.md), or [Cursor](https://docs.sqd.dev/en/ai/plugins-cursor.md) to get the MCP server and agent skills together.

<video autoPlay loop muted playsInline src="https://mintcdn.com/sqd-2119b3c3/KRRXbq03tb5ulLlM/files/portal-mcp-demo.mp4?fit=max&auto=format&n=KRRXbq03tb5ulLlM&q=85&s=08fb931c7a31002744df4934c24cc8b4" aria-label="Portal MCP server answering a blockchain data question inside an AI coding client" />

## Connect Portal MCP

* MCP endpoint: `https://portal.sqd.dev/mcp`
* Server version: [`0.8.6`](https://github.com/subsquid-labs/portal-mcp-server/releases/tag/v0.8.6)
* Authentication: none on the public server

> [tab] Claude Code
>
> ```bash theme={"system"}
> claude mcp add --transport http sqd-portal https://portal.sqd.dev/mcp
> ```
>
> Test the connection:
>
> ```bash theme={"system"}
> claude mcp list
> ```
>
> See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/mcp#installing-mcp-servers) for more details.

> [tab] Claude
>
> > [!TIP]
> >
> > SQD is in the [Claude Directory](https://claude.ai/directory/connectors/sqd). Add it in one click, no custom connector setup. See the [Claude Connector](https://docs.sqd.dev/en/ai/claude-connector.md) guide.
>
> **1. Add the SQD connector from the directory**
>
> Open the [SQD connector](https://claude.ai/directory/connectors/sqd) in the Claude Directory and select **Connect**. No sign-in or API key is required.
>
> **2. Enable it in your chat**
>
> 1. Select the **+** button (or type **/**) in the message box.
> 2. Hover over **Connectors** and toggle on **SQD**.
> 3. Ask Claude questions about blockchain data from Portal.
>
> Prefer to add it by URL instead? Add a custom connector pointing at `https://portal.sqd.dev/mcp`. See the [Model Context Protocol documentation](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server) for more details.

> [tab] Grok
>
> **1. Open Grok Connectors**
>
> Go to [grok.com/connectors](https://grok.com/connectors), select **New Connector**, then choose **Custom**.
>
> **2. Add SQD**
>
> Name the connector **SQD** and enter `https://portal.sqd.dev/mcp` as the MCP server URL. No authentication is required.
>
> **3. Try the connection**
>
> Start a new conversation and ask "Which blockchain networks can SQD query?" Grok should use the SQD tools to answer.
>
> Using Grok Build instead? Install the [SQD plugin for Grok](https://docs.sqd.dev/en/ai/plugins-grok.md) to get the MCP tools and four coding skills together.

> [tab] Cursor
>
> **1. Open MCP settings**
>
> 1. Use <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows) to open the command palette.
> 2. Search for "Open MCP settings".
> 3. Select **Add custom MCP**. This opens the `mcp.json` file.
>
> **2. Configure the Portal MCP server**
>
> In `mcp.json`, add:
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "sqd-portal": {
>       "url": "https://portal.sqd.dev/mcp"
>     }
>   }
> }
> ```
>
> **3. Test the connection**
>
> In Cursor's chat, ask "What tools do you have available?" Cursor should show the Portal MCP server as an available tool.
>
> See the [Cursor documentation](https://docs.cursor.com/en/context/mcp#installing-mcp-servers) for more details.

> [tab] VS Code
>
> Create a `.vscode/mcp.json` file and add:
>
> ```json theme={"system"}
> {
>   "servers": {
>     "sqd-portal": {
>       "type": "http",
>       "url": "https://portal.sqd.dev/mcp"
>     }
>   }
> }
> ```
>
> See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more details.

## Coverage and evidence

Portal MCP reports the data behind an answer and whether it covers the full request.

* **Verified time windows.** Timestamp boundaries are checked against indexed block timestamps across live datasets. The response shows the requested and analyzed window and rejects a future start time instead of silently moving it to the indexed head.
* **Stable evidence identities.** Normalized transactions, logs, calls, events, instructions, inputs, outputs, fills, and actions have stable row identifiers. Missing or duplicate identifiers fail the request rather than producing ambiguous evidence.
* **Exact continuation.** Cursor pages preserve every accepted row without duplicates or gaps, including multiple matching records in one block, and an oldest-first scan on logs, token transfers, and traces returns a working cursor too.
* **Reconciled totals.** Wallet quantities, transaction counts, aggregates, and OHLC summaries use the returned evidence and exact integer units. Token transfers use the token's own decimals. Hyperliquid fees stay signed and grouped by fee token; USD totals are unavailable when amounts or units are missing, invalid, or require conversion.
* **Disclosed partial reads.** A scan that stops before the start of the requested window reports `_coverage.window_complete: false` and names the blocks it searched, instead of a result that looks complete.
* **Interrupted scans.** Adaptive scans resume after the last completed block when delivery is interrupted. If the server cannot recover safely, it returns an error instead of replaying records and inflating totals.
* **Bounded, honest failures.** Response limits are measured on the actual MCP payload. Upstream overloads, timeouts, and incomplete results return structured retry guidance instead of partial data presented as complete.
* **Current MCP protocol.** Stateless HTTP supports MCP `2026-07-28`, including server discovery, request metadata, routing headers, and cache hints. Older clients continue through the SDK compatibility path.

## SQD Explorer (beta)

SQD Explorer is an optional MCP App, in beta and off by default. To enable it for your connection, use `https://portal.sqd.dev/mcp?app=1` in a client that supports MCP Apps.

Compatible clients show metrics, charts, price candles, evidence tables, coverage, and pagination controls for supported data tools. You can inspect chart values, filter evidence, request the next page, and export received records as JSON or CSV. Missing time buckets appear as gaps; display limits are separate from result completeness.

Tron queries return data through `portal_tron_query_transactions` and `portal_tron_query_logs`; the Explorer does not yet render Tron charts. Clients without MCP App support receive the same structured result and text fallback.

## Reproducible investigations

Three built-in MCP prompts provide guided starting points without adding more query tools:

* `investigate-wallet` for a wallet's bounded activity and evidence trail
* `investigate-contract` for interactions, callers, and emitted events
* `investigate-market` for fills, candles, volume, and market context

Material successful results include an `_evidence` receipt. It records the canonical tool arguments, argument and exact-data digests, source and analyzed windows, row reconciliation, completeness, and whether replay uses a pinned evidence window or a moving semantic window. Use the receipt together with `_coverage`, `_freshness`, `_ordering`, and `_pagination` before treating an answer as complete.

## Available tools

The server exposes 31 read-only tools: 28 query and analytics tools plus 3 low-level diagnostic tools. They cover EVM, Solana, Bitcoin, Substrate, Hyperliquid, and Tron data. Every tool uses the same pagination, error, and coverage format so the client can tell whether a result is complete or partial.

### Discovery & shared

| Tool | Description |
| - | - |
| `portal_list_networks` | Find the right network or alias across EVM, Solana, Bitcoin, Substrate, Hyperliquid, and Tron. First stop when you're not sure which dataset to query. |
| `portal_get_network_info` | Check if a network is indexed, fresh, caught up, or behind, and see which tables are available. |
| `portal_get_head` | Get just the latest or finalized head block or slot for a network. |
| `portal_resolve_entity` | Resolve token symbols, contract aliases, pool IDs, protocol names, and Hyperliquid coins into query-ready addresses and filters before building a query. |
| `portal_get_recent_activity` | Cross-VM recent-activity feed with chronological paging. Simplest answer to "what's been happening on X lately?". |
| `portal_get_wallet_summary` | One-call wallet analysis across supported VMs. Overview, activity, and assets. |
| `portal_get_time_series` | Chart-ready metric buckets over time with optional compare-to-previous and EVM contract grouping. |

### EVM

| Tool | Description |
| - | - |
| `portal_evm_query_transactions` | Query raw EVM transactions with optional logs, traces, and state-diff context via include flags. |
| `portal_evm_query_logs` | Query raw EVM logs with address/topic filters and optional inline decoding. |
| `portal_evm_query_traces` | Query raw EVM traces: internal calls, contract creations, self-destructs, and block rewards, with the parent transaction hash on every row. |
| `portal_evm_query_token_transfers` | Token-transfer activity on EVM without needing to remember the Transfer event signature. |
| `portal_evm_get_analytics` | Network-wide EVM snapshot with ranked top contracts and compact overview metrics. |
| `portal_evm_get_contract_activity` | Contract-centric summary: recent interactions, unique callers, and optional event activity. |
| `portal_evm_get_contract_deployment` | Look up the deployment block, transaction, and deployer for any EVM contract address. |
| `portal_evm_get_ohlc` | **Experimental.** DEX OHLC candles plus a recent-trade tape from Uniswap v2/v3/v4 and Aerodrome Slipstream swaps. |

### Solana

| Tool | Description |
| - | - |
| `portal_solana_query_transactions` | Query raw Solana transactions with optional balances, token balances, rewards, logs, and instruction context. |
| `portal_solana_query_instructions` | Query raw instructions with program, account, and Anchor-discriminator filters. |
| `portal_solana_get_analytics` | Solana throughput, fee, wallet activity, and optional top-program snapshot. |

### Bitcoin

| Tool | Description |
| - | - |
| `portal_bitcoin_query_transactions` | Query raw Bitcoin transactions with optional inline inputs and outputs. |
| `portal_bitcoin_get_analytics` | Bitcoin block cadence, fees, SegWit/Taproot adoption, and address activity snapshot. |

### Hyperliquid

| Tool | Description |
| - | - |
| `portal_hyperliquid_query_fills` | Query trade fills with PnL, fees, and routing. |
| `portal_hyperliquid_get_analytics` | Trading volume, top coins, and trader rankings. |
| `portal_hyperliquid_get_ohlc` | OHLC candles for Hyperliquid markets. |

### Substrate

Substrate data is historical only, with no real-time tail.

| Tool | Description |
| - | - |
| `portal_substrate_query_calls` | Query Polkadot-, Kusama-, and other Substrate-style extrinsic calls with pallet and method filters. |
| `portal_substrate_query_events` | Query Substrate events emitted by runtime pallets. |
| `portal_substrate_get_analytics` | Substrate network-wide snapshot: block cadence, extrinsic volume, and top pallets. |

### Tron

| Tool | Description |
| - | - |
| `portal_tron_query_transactions` | Query raw Tron transactions: native TRX transfers, TRC-10 asset transfers, and smart-contract calls, with optional inline logs and internal transactions. Addresses accept Base58 or hex. |
| `portal_tron_query_logs` | Query raw Tron (TVM) event logs, such as TRC-20 transfers, by contract address and topic, with the parent transaction hash on every row. |

### Debug

| Tool | Description |
| - | - |
| `portal_debug_query_blocks` | Inspect raw blocks across VMs for schema debugging. |
| `portal_debug_resolve_time_to_block` | Resolve a timestamp to a block or slot for any supported network. |
| `portal_debug_hyperliquid_query_replica_commands` | Low-level access to Hyperliquid replica commands (orders, cancels, transfers, leverage updates). |

### Analytics limits

* Hyperliquid volume is per-account fill notional, not deduplicated market volume. Liquidation metrics are unavailable because Portal fills do not expose a liquidation marker.
* If an optional Solana instruction scan fails, program rankings are marked unavailable. Transaction analytics remain available.

## Response size and pagination

The MCP query tools return a **bounded page** of results plus a `_pagination.next_cursor` when more matching rows are available. The page is sized to fit an AI context window, so one call may return a preview rather than the whole range. Pass `next_cursor` back until `_coverage.result_complete` is `true`, or tighten the filters.

Check `_coverage.window_complete` separately. A complete result page can still cover only the scanned part of a wider requested window. The server keeps this distinction explicit and never silently removes rows to fit a response.

Raw query tools can return capped results for wide ranges. `portal_get_time_series` rejects windows over 12,000 blocks, so use shorter windows on fast chains. Time-series requests for Base mainnet and Sepolia default to 15 minutes.

The underlying [Stream API](https://docs.sqd.dev/en/portal/solana/api.md) behaves differently: it has no per-response page cap and streams the full result at HTTP 200 (bounded only server-side), and you paginate it by resuming from `lastBlock + 1` rather than a cursor. The MCP's paging is a separate convenience layer for AI clients, not a limit on the HTTP API.

## Known limitations

Portal MCP is designed for bounded answers inside an AI conversation. Broad, unfiltered scans on dense networks can return partial coverage or reach the request timeout. Check the coverage and pagination fields, narrow the filters, or request the next page. Use the raw Portal Stream API or an indexer for complete exports and recurring workloads.

## Related

* [Claude Code Plugin](https://docs.sqd.dev/en/ai/plugins-claude.md). One-command plugin install for Claude Code
* [Codex Plugin](https://docs.sqd.dev/en/ai/plugins-codex.md). One-command plugin install for Codex
* [Grok Plugin](https://docs.sqd.dev/en/ai/plugins-grok.md). Install SQD in Grok Build or connect Grok on the web
* [Gemini CLI Extension](https://docs.sqd.dev/en/ai/plugins-gemini.md). Install SQD in Gemini CLI
* [Cursor Plugin](https://docs.sqd.dev/en/ai/plugins-cursor.md). Install SQD in Cursor
* [AI Development Overview](https://docs.sqd.dev/en/ai/ai-development.md). Resources for building AI agents with SQD
* [Portal API Reference](https://docs.sqd.dev/en/portal/evm/overview.md). HTTP API for blockchain data
* [Documentation MCP Server](https://docs.sqd.dev/en/ai/mcp-server-docs.md). Search SQD documentation
* [Pipes SDK](https://docs.sqd.dev/en/sdk/pipes-sdk/evm/quickstart.md). TypeScript SDK for custom pipelines
* [llms.txt](https://docs.sqd.dev/llms.txt). Documentation index for LLMs


## Related topics

- [Agent Skills](https://docs.sqd.dev/en/ai/agent-skills.md)
- [AI Development](https://docs.sqd.dev/en/ai/ai-development.md)
- [SQD Connector for Claude](https://docs.sqd.dev/en/ai/claude-connector.md)
- [Documentation MCP Server](https://docs.sqd.dev/en/ai/mcp-server-docs.md)
- [SQD plugin for Claude Code](https://docs.sqd.dev/en/ai/plugins-claude.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.