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

# Helius MCP Server

> MCP server for Helius — 9 routed tools plus expandResult give AI assistants Solana querying, transaction sending, webhooks, streaming, and wallet analysis.

The [Helius MCP server](https://www.npmjs.com/package/helius-mcp) gives AI tools direct access to Helius APIs through **10 public tools** — 9 routed domain tools that cover all Helius and Solana functionality, plus `expandResult` for paging through large responses.

> [card] 9 Routed Tools
>
> Domain-grouped tools (`heliusWallet`, `heliusAsset`, `heliusTransaction`, …) — every Helius action is reachable through one of them

> [card] Account Signup
>
> Create a Helius account from your AI tool — pay via hosted link or autopay USDC from a local keypair

> [card] Real-Time Data
>
> Subscribe to Enhanced WebSockets and LaserStream gRPC directly from your AI tool

> [card] Any MCP Client
>
> Works with Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Codex, and any MCP-compatible tool

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open-source standard introduced by Anthropic that allows AI models to securely connect with external data sources, tools, and APIs. It uses a client-server architecture where a host (like Claude) connects to an MCP server, allowing the AI to query databases, call APIs, or execute actions through a universal, standardized interface.

**Why this matters for Helius:** The MCP gives Claude direct access to live Solana data and Helius infrastructure — balances, asset metadata, parsed transactions, webhook management, streaming, and more. Without it, Claude has to guess at API responses or make repeated curl requests to gain context. The MCP lets Claude actually interact with Solana through Helius using structured tool calls.

> [!NOTE]
>
> The Helius docs site at [helius.dev/docs](https://www.helius.dev/docs/index.md) also exposes a separate MCP server auto-generated by Mintlify. That server is scoped to documentation search only. `helius-mcp` documented here is the comprehensive server covering all Helius and Solana functionality.

## Quick Start

**1. Add the MCP server**

```bash theme={"system"}
claude mcp add helius npx helius-mcp@latest
```

Or add to your MCP host's config (Claude Desktop, Cursor, Windsurf, VS Code, etc.):

```json theme={"system"}
{
  "mcpServers": {
    "helius": {
      "command": "npx",
      "args": ["helius-mcp@latest"]
    }
  }
}
```

**2. Configure your API key**

**If you already have a key:**

```bash theme={"system"}
export HELIUS_API_KEY=YOUR_API_KEY
```

Or set it inside Claude by calling the `setHeliusApiKey` action on `heliusAccount`. API keys are resolved in this order:

1. `setHeliusApiKey` action call within the session
2. `HELIUS_API_KEY` environment variable
3. `~/.helius/config.json` (set via the [Helius CLI](https://www.helius.dev/docs/agents/cli.md))

**If you need a new account:** See [Signup](#signup) below.

**3. Start using tools**

Ask questions in plain English — the right tool and action are selected automatically:

* "What NFTs does this wallet own?"
* "Parse this transaction: `5abc...`"
* "Get the balance of `Gh9ZwEm...`"
* "Send 1 SOL to `7xKp...`"
* "Create a webhook for this address"

## Connecting to the Helius MCP Server

> [tab] Claude Code
>
> Run the following command:
>
> ```bash theme={"system"}
> claude mcp add helius npx helius-mcp@latest
> ```
>
> Or add to your project's `.mcp.json`:
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "helius": {
>       "command": "npx",
>       "args": ["helius-mcp@latest"]
>     }
>   }
> }
> ```
>
> Verify with:
>
> ```bash theme={"system"}
> claude mcp list
> ```
>
> > [!TIP]
> >
> > Want skills + MCP in one step? Install the [Helius plugin](https://www.helius.dev/docs/agents/claude-code-plugin.md) instead. Run these as two separate commands:
> >
> > ```
> > /plugin marketplace add helius-labs/core-ai
> > ```
> >
> > ```
> > /plugin install helius@helius-labs
> > ```

> [tab] Claude Desktop
>
> Open **Settings > Developer > Edit Config** and add the server:
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "helius": {
>       "command": "npx",
>       "args": ["helius-mcp@latest"]
>     }
>   }
> }
> ```
>
> Restart Claude Desktop to apply.

> [tab] Cursor
>
> Open the command palette (`Cmd/Ctrl + Shift + P`), search for **MCP: Add Server**, and enter:
>
> * **Name:** `helius`
> * **Command:** `npx helius-mcp@latest`
>
> Or add to your project's `.cursor/mcp.json`:
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "helius": {
>       "command": "npx",
>       "args": ["helius-mcp@latest"]
>     }
>   }
> }
> ```

> [tab] VS Code
>
> Create a `.vscode/mcp.json` file in your project root:
>
> ```json theme={"system"}
> {
>   "servers": {
>     "helius": {
>       "command": "npx",
>       "args": ["helius-mcp@latest"]
>     }
>   }
> }
> ```
>
> Requires the [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) extension with MCP support enabled.

> [tab] Windsurf
>
> Open the command palette (`Cmd/Ctrl + Shift + P`), search for **Configure MCP Servers**, and add:
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "helius": {
>       "command": "npx",
>       "args": ["helius-mcp@latest"]
>     }
>   }
> }
> ```

> [tab] Codex
>
> Run the following command:
>
> ```bash theme={"system"}
> codex mcp add helius -- npx helius-mcp@latest
> ```
>
> Or add to your `~/.codex/config.toml` (or `.codex/config.toml` for project-scoped):
>
> ```toml theme={"system"}
> [mcp_servers.helius]
> command = "npx"
> args = ["helius-mcp@latest"]
> ```
>
> Verify with:
>
> ```bash theme={"system"}
> codex mcp list
> ```

## Read-Only Mode

Read-only mode serves only actions that can't move funds or change account state. Use it where an agent should read chain data but must never sign or send, such as directory-listed or shared deployments.

Start the server with the `--read-only` flag:

```bash theme={"system"}
npx helius-mcp@latest --read-only
```

Or set the `HELIUS_MCP_READ_ONLY` environment variable:

```bash theme={"system"}
export HELIUS_MCP_READ_ONLY=1
```

Any value other than unset, empty, `0`, or `false` turns read-only mode on, so a typo leaves the server read-only, not writable.

### Set your API key on a read-only server

The `setHeliusApiKey` action isn't available in read-only mode. Set your key with the `HELIUS_API_KEY` environment variable instead:

```json theme={"system"}
{
  "mcpServers": {
    "helius": {
      "command": "npx",
      "args": ["helius-mcp@latest", "--read-only"],
      "env": {
        "HELIUS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

### What read-only mode removes

A read-only server exposes **9 public tools**: `heliusWrite` isn't registered at all. These 15 actions are removed:

| Tool | Removed actions |
| - | - |
| `heliusWrite` | `transferSol`, `transferToken`, `stakeSOL`, `unstakeSOL`, `withdrawStake` |
| `heliusAccount` | `setHeliusApiKey`, `generateKeypair`, `signup`, `upgradePlan`, `payRenewal`, `purchaseCredits` |
| `heliusStreaming` | `createWebhook`, `updateWebhook`, `deleteWebhook`, `toggleWebhook` |

`recommendStack` stays available, but its `remember` option, which saves preferences locally, is removed.

### Tool annotations

Every tool, in both modes, declares MCP tool annotations: a title plus read-only, destructive, idempotent, and open-world hints. Clients that honor them can ask for confirmation before destructive actions.

## Public Tool Surface

Helius MCP exposes **10 public tools**: 9 routed domain tools plus `expandResult`. Every Helius and Solana action is reachable as an `action` argument on the appropriate routed tool.

| Tool | Scope |
| - | - |
| `heliusAccount` | Account setup, auth, plans, billing |
| `heliusWallet` | Wallet balances, holdings, history, identity |
| `heliusAsset` | Assets, NFTs, collections, token holders |
| `heliusTransaction` | Transaction parsing, wallet transaction history, and server-side history search |
| `heliusChain` | Chain state, token accounts, blocks, network status, program accounts, Jito bundle simulation and status |
| `heliusStreaming` | Webhook management and subscription config (WebSockets, LaserStream, Parsed Streams, Preconfirmations, Preprocessed Transactions) |
| `heliusKnowledge` | Docs, guides, pricing, troubleshooting, source, blog, SIMDs |
| `heliusWrite` | Transfers (SOL and SPL tokens) and staking |
| `heliusCompression` | ZK Compression accounts, balances, proofs, and signatures |
| `expandResult` | Expand summary-first outputs by `resultId` |

In [read-only mode](#read-only-mode), `heliusWrite` isn't registered and actions that change state are removed.

> [card] [Full Tool Catalog](https://www.helius.dev/docs/agents/mcp/tools.md)
>
> Every action grouped by routed tool, with call-shape details and `expandResult` usage

### Routed tool call shape

Each of the 9 routed tools shares a common shape:

* `action` — the Helius action name to run, such as `getBalance` or `createWebhook`
* domain-specific params — for example `address`, `signatures`, or `webhookURL`
* optional `detail` — `summary`, `standard`, or `full`
* telemetry fields — `_feedback`, `_feedbackTool`, `_model`

Example call:

```json theme={"system"}
{
  "name": "heliusWallet",
  "arguments": {
    "action": "getBalance",
    "address": "Gh9ZwEmdLJ8DscKNTkTqPbNwLNNBjuSzaG9Vp2KGtKJr",
    "_feedback": "initial balance check",
    "_feedbackTool": "heliusWallet.getBalance",
    "_model": "your-model-id"
  }
}
```

### Summary-first responses and `expandResult`

Heavy responses are **summary-first**. Routed tools return a compact summary plus a `resultId` when the full response would be large or when `detail: "summary"` is requested. Use `expandResult` with that `resultId` to fetch a specific section, range, page, or continuation slice on demand.

This keeps token usage low for exploratory queries while still letting agents drill into the full payload when needed.

## Signup

Create a Helius account from your AI tool through a hosted payment link or by paying USDC directly from a local keypair. The signup flow runs through the `heliusAccount` routed tool:

**1. Generate a keypair**

The AI calls `heliusAccount` with `action: "generateKeypair"` — it creates a Solana wallet and returns the address.

**2. Create the payment intent**

The AI calls `heliusAccount` with `action: "signup"` and `mode: "link"` — returns a `paymentUrl` (e.g. `https://dashboard.helius.dev/pay/<id>`) the user opens to pay with any wallet. Or pass `mode: "autopay"` to send USDC from the local keypair automatically (wallet must hold \~0.001 SOL + the plan amount in USDC).

**3. Resume after payment**

After paying via link, the AI calls `heliusAccount` with `action: "signup"` and `mode: "resume"` — polls the payment intent, finalizes account provisioning, and configures the API key automatically.

> [!NOTE]
>
> **Contact info:** every new signup — including the Agent plan — requires `email`, `firstName`, and `lastName`. The wallet is only used to pay. `upgradePlan` requires the same.

Or do the same from the terminal with the [Helius CLI](https://www.helius.dev/docs/agents/cli.md):

```bash theme={"system"}
npx helius-cli@latest keygen
npx helius-cli@latest signup --plan agent --email you@example.com --first-name Jane --last-name Doe   # Print hosted payment link
# (pay in browser, then:)
npx helius-cli@latest signup --resume         # Finalize account
# Or autopay from the local keypair:
npx helius-cli@latest signup --plan agent --pay --email you@example.com --first-name Jane --last-name Doe
```

## Network Configuration

The MCP server defaults to **mainnet-beta**. Switch to devnet via environment variable:

```bash theme={"system"}
export HELIUS_NETWORK=devnet
```

Or call the `setNetwork` action on `heliusAccount` within a session.

## System Prompts

The `helius-mcp` package ships with pre-built system prompts that teach AI models how to use Helius tools effectively. They live in `system-prompts/`:

```
system-prompts/
├── helius/              # Core Helius skill
├── helius-phantom/      # Phantom frontend skill
├── helius-jupiter/      # Jupiter DeFi skill
├── helius-dflow/        # DFlow trading skill
├── helius-okx/          # OKX trading & intelligence skill
└── svm/                 # SVM architecture skill
```

Each contains three variants:

* `openai.developer.md` — for OpenAI Responses/Chat Completions API (`developer` message)
* `claude.system.md` — for Claude API (system prompt)
* `full.md` — self-contained with all references inlined (Cursor Rules, ChatGPT, etc.)

See the [`helius-skills/SYSTEM-PROMPTS.md`](https://github.com/helius-labs/core-ai/blob/main/helius-skills/SYSTEM-PROMPTS.md) integration guide for code examples.

## Skills

Skills are expert instruction sets that teach Claude how to route your requests to the right MCP actions and reference files. They go beyond raw tool access — they include routing logic, correct SDK patterns, and rules that prevent common mistakes.

> [card] [Skills Overview](https://www.helius.dev/docs/agents/skills/overview.md)
>
> Six skills available: Build (general Solana dev), Phantom (frontend dApps), Jupiter (DeFi), DFlow (trading apps), OKX (trading and intelligence), and SVM (protocol internals)

## Learn More

> [card] [Claude Code Plugin](https://www.helius.dev/docs/agents/claude-code-plugin.md)
>
> One-click install of MCP + skills

> [card] [Helius CLI](https://www.helius.dev/docs/agents/cli.md)
>
> Command-line account management

> [card] [MCP Specification](https://modelcontextprotocol.io/)
>
> Learn about the Model Context Protocol standard

> [card] [helius-mcp on npm](https://www.npmjs.com/package/helius-mcp)
>
> Package details and version history

> [card] [Changelog](https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CHANGELOG.md)
>
> Version history and release notes

> [card] [Contribute](https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CONTRIBUTING.md)
>
> Contribution guide for `helius-mcp`


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