> ## 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.

# Servidor Helius MCP

> Servidor MCP para Helius — 10 ferramentas roteadas que dão aos assistentes de IA acesso total a consultas Solana, envio de transações, webhooks, streaming, análise de carteiras e cadastro autônomo de contas.

O [servidor Helius MCP](https://www.npmjs.com/package/helius-mcp) oferece às ferramentas de IA acesso direto às APIs do Helius por meio de **10 ferramentas públicas** — 9 ferramentas de domínio roteado que cobrem toda a funcionalidade do Helius e Solana, além de `expandResult` para paginação de grandes respostas.

<CardGroup cols={2}>
  <Card title="9 Ferramentas Roteadas" icon="bolt">
    Ferramentas agrupadas por domínio (`heliusWallet`, `heliusAsset`, `heliusTransaction`, …) — cada ação do Helius é acessível através de uma delas.
  </Card>

  <Card title="Cadastro de Conta" icon="robot">
    Crie uma conta Helius a partir da sua ferramenta de IA — pague via link hospedado ou autopagamento USDC de um par de chaves local.
  </Card>

  <Card title="Dados em Tempo Real" icon="signal-stream">
    Assine Enhanced WebSockets e LaserStream gRPC diretamente da sua ferramenta de IA.
  </Card>

  <Card title="Qualquer Cliente MCP" icon="plug">
    Funciona com Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Codex e qualquer ferramenta compatível com MCP.
  </Card>
</CardGroup>

## O que é MCP?

O [Protocolo de Contexto do Modelo (MCP)](https://modelcontextprotocol.io/) é um padrão de código aberto introduzido pela Anthropic que permite que modelos de IA se conectem de forma segura a fontes de dados externas, ferramentas e APIs. Ele utiliza uma arquitetura cliente-servidor onde um host (como Claude) se conecta a um servidor MCP, permitindo que a IA consulte bancos de dados, chame APIs ou execute ações por meio de uma interface universal e padronizada.

**Por que isso é importante para o Helius:** O MCP dá ao Claude acesso direto a dados ao vivo do Solana e infraestrutura do Helius — saldos, metadados de ativos, transações analisadas, gerenciamento de webhooks, streaming e mais. Sem ele, Claude teria que adivinhar as respostas da API ou fazer solicitações curl repetidas para obter contexto. O MCP permite que Claude interaja realmente com Solana através do Helius usando chamadas de ferramenta estruturadas.

<Note>
  O site de documentação do Helius em [helius.dev/docs](https://www.helius.dev/docs) também expõe um servidor MCP separado gerado automaticamente pela Mintlify. Esse servidor é limitado apenas à pesquisa de documentação. `helius-mcp` documentado aqui é o servidor abrangente que cobre toda a funcionalidade do Helius e Solana.
</Note>

## Início Rápido

<Steps>
  <Step title="Adicionar o servidor MCP">
    ```bash theme={"system"}
    claude mcp add helius npx helius-mcp@latest
    ```

    Ou adicione à configuração do host MCP (Claude Desktop, Cursor, Windsurf, VS Code, etc.):

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

  <Step title="Configure sua chave de API">
    **Se você já tem uma chave:**

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

    Ou defina dentro do Claude chamando a ação `setHeliusApiKey` em `heliusAccount`. As chaves de API são resolvidas nesta ordem:

    1. Chamada de ação `setHeliusApiKey` dentro da sessão
    2. Variável de ambiente `HELIUS_API_KEY`
    3. `~/.helius/config.json` (definida via [Helius CLI](/docs/pt-BR/agents/cli))

    **Se você precisa de uma nova conta:** Veja [Cadastro](#signup) abaixo.
  </Step>

  <Step title="Comece a usar as ferramentas">
    Faça perguntas em inglês simples — a ferramenta e a ação corretas são selecionadas automaticamente:

    * "Quais NFTs essa carteira possui?"
    * "Analise esta transação: `5abc...`"
    * "Obtenha o saldo de `Gh9ZwEm...`"
    * "Envie 1 SOL para `7xKp...`"
    * "Crie um webhook para este endereço"
  </Step>
</Steps>

## Conectando ao Servidor Helius MCP

<Tabs>
  <Tab title="Claude Code">
    Execute o seguinte comando:

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

    Ou adicione ao `.mcp.json` do seu projeto:

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

    Verifique com:

    ```bash theme={"system"}
    claude mcp list
    ```

    <Tip>
      Quer habilidades + MCP em um passo? Instale o [plugin Helius](/docs/pt-BR/agents/claude-code-plugin) em vez disso:

      ```bash theme={"system"}
      claude plugin install helius @claude-plugins-official
      ```

      Ou no marketplace do Helius:

      ```
      /plugin marketplace add helius-labs/core-ai
      /plugin install helius@helius-labs
      ```
    </Tip>
  </Tab>

  <Tab title="Claude Desktop">
    Abra **Configurações > Desenvolvedor > Editar Configuração** e adicione o servidor:

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

    Reinicie o Claude Desktop para aplicar.
  </Tab>

  <Tab title="Cursor">
    Abra o palete de comandos (`Cmd/Ctrl + Shift + P`), procure por **MCP: Add Server**, e insira:

    * **Nome:** `helius`
    * **Comando:** `npx helius-mcp@latest`

    Ou adicione ao `.cursor/mcp.json` do seu projeto:

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

  <Tab title="VS Code">
    Crie um arquivo `.vscode/mcp.json` na raiz do seu projeto:

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

    Requer a extensão [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) com suporte MCP habilitado.
  </Tab>

  <Tab title="Windsurf">
    Abra o palete de comandos (`Cmd/Ctrl + Shift + P`), procure por **Configure MCP Servers**, e adicione:

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

  <Tab title="Codex">
    Execute o seguinte comando:

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

    Ou adicione ao seu `~/.codex/config.toml` (ou `.codex/config.toml` para âmbito do projeto):

    ```toml theme={"system"}
    [mcp_servers.helius]
    command = "npx"
    args = ["helius-mcp@latest"]
    ```

    Verifique com:

    ```bash theme={"system"}
    codex mcp list
    ```
  </Tab>
</Tabs>

## Superfície de Ferramenta Pública

O Helius MCP expõe **10 ferramentas públicas**: 9 ferramentas de domínio roteado mais `expandResult`. Cada ação do Helius e Solana é acessível como um argumento `action` na ferramenta roteada apropriada.

| Ferramenta          | Escopo                                                                         |
| ------------------- | ------------------------------------------------------------------------------ |
| `heliusAccount`     | Configuração de conta, autenticação, planos, faturamento                       |
| `heliusWallet`      | Saldos de carteira, participações, histórico, identidade                       |
| `heliusAsset`       | Ativos, NFTs, coleções, detentores de tokens                                   |
| `heliusTransaction` | Análise de transações e histórico de transações de carteira                    |
| `heliusChain`       | Estado da cadeia, contas de token, blocos, status da rede, contas de programas |
| `heliusStreaming`   | CRUD de webhook e configuração de assinaturas (WebSockets, LaserStream)        |
| `heliusKnowledge`   | Documentos, guias, preços, resolução de problemas, fonte, blog, SIMDs          |
| `heliusWrite`       | Transferências — tokens SOL e SPL                                              |
| `heliusCompression` | Provas Merkle para NFTs comprimidos                                            |
| `expandResult`      | Expanda saídas resumo-primeiro por `resultId`                                  |

<Card title="Catálogo Completo de Ferramentas" icon="bolt" href="/docs/pt-BR/agents/mcp/tools">
  Cada ação agrupada por ferramenta roteada, com detalhes de formato de chamada e uso de `expandResult`
</Card>

### Formato de chamada da ferramenta roteada

Cada uma das 9 ferramentas roteadas compartilha um formato comum:

* `action` — o nome da ação do Helius a executar, como `getBalance` ou `createWebhook`
* parâmetros específicos do domínio — por exemplo `address`, `signatures`, ou `webhookURL`
* opcional `detail` — `summary`, `standard`, ou `full`
* campos de telemetria — `_feedback`, `_feedbackTool`, `_model`

Exemplo de chamada:

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

### Respostas resumo-primeiro e `expandResult`

Respostas pesadas são **resumo-primeiro**. Ferramentas roteadas retornam um resumo compacto mais um `resultId` quando a resposta completa seria grande ou quando `detail: "summary"` é solicitado. Use `expandResult` com esse `resultId` para buscar uma seção específica, intervalo, página ou fragmento de continuação sob demanda.

Isso mantém o uso de tokens baixo para consultas exploratórias, mas ainda permite que os agentes explorem o payload completo quando necessário.

## Cadastro

Crie uma conta Helius a partir da sua ferramenta de IA através de um link de pagamento hospedado ou pagando USDC diretamente de um par de chaves local. O fluxo de cadastro acontece através da ferramenta roteada `heliusAccount`:

<Steps>
  <Step title="Gerar um par de chaves">
    A IA chama `heliusAccount` com `action: "generateKeypair"` — ele cria uma carteira Solana e retorna o endereço.
  </Step>

  <Step title="Crie a intenção de pagamento">
    A IA chama `heliusAccount` com `action: "signup"` e `mode: "link"` — retorna um `paymentUrl` (por exemplo, `https://dashboard.helius.dev/pay/<id>`) que o usuário abre para pagar com qualquer carteira. Ou passe `mode: "autopay"` para enviar USDC do par de chaves local automaticamente (a carteira deve conter \~0.001 SOL + o valor do plano em USDC).
  </Step>

  <Step title="Retome após o pagamento">
    Após pagar via link, a IA chama `heliusAccount` com `action: "signup"` e `mode: "resume"` — verifica a intenção de pagamento, finaliza o provisionamento da conta e configura a chave de API automaticamente.
  </Step>
</Steps>

<Note>
  **Informações de contato:** cada novo cadastro — incluindo o plano Agent — requer `email`, `firstName` e `lastName`. `upgradePlan` requer o mesmo.
</Note>

Ou faça o mesmo a partir do terminal com o [Helius CLI](/docs/pt-BR/agents/cli):

```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
```

## Configuração de Rede

O servidor MCP é padrão para **mainnet-beta**. Mude para devnet via variável de ambiente:

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

Ou chame a ação `setNetwork` em `heliusAccount` dentro de uma sessão.

## Prompts do Sistema

O pacote `helius-mcp` vem com prompts de sistema pré-construídos que ensinam os modelos de IA a usar as ferramentas Helius de forma eficaz. Eles estão em `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
```

Cada um contém três variantes:

* `openai.developer.md` — para OpenAI Responses/Chat Completions API (mensagem `developer`)
* `claude.system.md` — para Claude API (prompt de sistema)
* `full.md` — autossuficiente com todas as referências incorporadas (Cursor Rules, ChatGPT, etc.)

Consulte o guia de integração [`helius-skills/SYSTEM-PROMPTS.md`](https://github.com/helius-labs/core-ai/blob/main/helius-skills/SYSTEM-PROMPTS.md) para exemplos de código.

## Habilidades

Habilidades são conjuntos de instruções especializadas que ensinam o Claude a direcionar suas solicitações para as ações MCP certas e arquivos de referência. Elas vão além do acesso bruto às ferramentas — incluem lógica de roteamento, padrões corretos de SDK e regras que evitam erros comuns.

<Card title="Visão Geral das Habilidades" icon="brain" href="/docs/pt-BR/agents/skills/overview">
  Seis habilidades disponíveis: Build (desenvolvimento geral Solana), Phantom (dApps frontend), Jupiter (DeFi), DFlow (aplicativos de negociação), OKX (negociação e inteligência) e SVM (internals de protocolo)
</Card>

## Saiba Mais

<CardGroup cols={2}>
  <Card title="Plugin Claude Code" icon="puzzle-piece" href="/docs/pt-BR/agents/claude-code-plugin">
    Instalação com um clique de MCP + habilidades
  </Card>

  <Card title="Helius CLI" icon="terminal" href="/docs/pt-BR/agents/cli">
    Gerenciamento de contas via linha de comando
  </Card>

  <Card title="Especificação MCP" icon="book" href="https://modelcontextprotocol.io/">
    Saiba mais sobre o padrão Model Context Protocol
  </Card>

  <Card title="helius-mcp no npm" icon="npm" href="https://www.npmjs.com/package/helius-mcp">
    Detalhes do pacote e histórico de versões
  </Card>

  <Card title="Changelog" icon="list" href="https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CHANGELOG.md">
    Histórico de versões e notas de lançamento
  </Card>

  <Card title="Contribuir" icon="github" href="https://github.com/helius-labs/core-ai/blob/main/helius-mcp/CONTRIBUTING.md">
    Guia de contribuição para `helius-mcp`
  </Card>
</CardGroup>