Helio MCP Governance Proxy

Helio

Proxy de governança open-source para agentes de IA

Começando · Documentação · Contribuindo

---

Helio é um proxy MCP que fica entre seus agentes de IA e as ferramentas que eles usam. Cada chamada de ferramenta passa pelo Helio, que aplica políticas, verifica evidências, roteia aprovações, limita gastos acumulados e registra tudo - sem alterar o código do seu agente ou seus servidores MCP.

npx @gethelio/proxy init

@gethelio/proxy é o único pacote Node que você instala. Ele inclui o runtime do proxy e os assets da interface do dashboard em um único pacote.

Por que Helio?

Seu agente acabou de chamar uma API que você não esperava. Gastou dinheiro que você não autorizou. Modificou um registro de produção que você não pode desfazer facilmente.

Provedores de modelos estão construindo governança para suas próprias plataformas, mas seus agentes rodam em Claude, ChatGPT, LangChain, CrewAI e frameworks personalizados. Nenhuma plataforma única governa o quadro completo. E nenhuma delas governa o que acontece em sistemas downstream como Stripe, Salesforce ou GitHub.

O Helio governa o que os agentes fazem com o resto do mundo em qualquer agente compatível com MCP, qualquer ferramenta, qualquer plataforma.

Uma regra no Helio não pode ser esquecida e não pode ser enfraquecida silenciosamente. Ela não está no contexto do modelo, então uma sessão longa não pode expulsá-la e uma injeção não pode contestá-la, e a aplicação está no caminho em vez do prompt: uma chamada de ferramenta roteada pelo Helio é decidida antes de ser encaminhada, independentemente do que o modelo foi instruído. Cada tentativa de recarregar o arquivo de política, incluindo uma que remove uma regra, é um registro de auditoria, e cada registro carrega o hash da configuração em vigor quando foi escrito, então uma mudança aparece contra as decisões tomadas sob ela. A afirmação "não pode ser enfraquecida silenciosamente" tem uma condição, declarada em Graus de aplicação.

Como Funciona

Dois caminhos de integração:

1. Somente proxy: Aponte seu cliente MCP para o Helio em vez do seu servidor MCP. Zero mudanças de código. Governança imediata.
2. Proxy + SDK: Adicione o SDK Python leve para anotar chamadas de ferramenta com contexto de evidência e dependências de ação. Governança mais rica, com menos de 500 linhas de código.

Graus de aplicação

O Helio governa no grau mais forte que cada caminho permite fisicamente e registra isso por chamada:

• Estrutural (stdio MCP) — O Helio possui o processo filho que ele iniciou, então nada no caminho MCP pode contorná-lo; um processo co-localizado que pode executar a mesma linha de comando está fora deste grau (veja a nota abaixo).
• Rede (HTTP MCP) — estrutural, desde que você controle a saída do upstream.
• Imposto pelo host (adaptadores de hook via API de adaptadores, ex.: OpenClaw) — para frameworks que executam ferramentas in-process e expõem hooks em vez de um transporte MCP. O gate de hooks do framework aplica; o Helio decide. Este é um grau cooperativo, mais baixo que o caminho de proxy, e o Helio o rotula como tal em vez de superestimar. As decisões do Helio ainda não podem ser expulsas do contexto do agente ou injetadas por prompt, e qualquer tentativa de contorná-las é visível no trilho de auditoria.

Todos os três graus assumem que a configuração, o segredo e o armazenamento de auditoria do proxy estão fora do alcance do agente. Na instalação local padrão, eles não estão: o proxy roda como o mesmo usuário que o agente. SECURITY.md declara o limite e as implantações que o fecham. Essa instalação também é a condição para "não pode ser enfraquecida silenciosamente": um agente do mesmo usuário pode reiniciar o proxy sem o pin de configuração e pode editar ou excluir o arquivo de auditoria, então o registro de recarga e o hash em cada registro são duráveis apenas enquanto o agente não puder escrever o arquivo de auditoria, e o stream de eventos e o stderr são os canais que saem da máquina antes disso. Rode o proxy como seu próprio usuário ou em seu próprio contêiner, como as receitas lá fazem, e a condição desaparece.

Início Rápido (5 minutos)

1. Instalar

npx @gethelio/proxy init

Este pacote único inclui o bundle da interface do dashboard embutido.

Rodando seu agente em um contêiner? npx @gethelio/proxy init --sandbox escreve o layout sidecar; veja Rodando Helio como Sidecar.

2. Configurar

npx @gethelio/proxy init já criou um helio.yaml na raiz do seu projeto. Abra-o (ex.: nano helio.yaml, ou no seu editor) e aponte upstream.url para o seu servidor MCP existente. A forma singular upstream: permanece totalmente suportada; para governar mais de um servidor MCP, declare uma lista nomeada upstreams: em seu lugar (defina exatamente um dos dois). Conjuntos de ferramentas nunca são mesclados: cada upstream nomeado é servido em sua própria porta /mcp/<name>. Veja a Referência de Configuração.

Atenção — o Helio inicia em modo somente auditoria. init cria a seção policies comentada, então, por padrão, o Helio roda com default: allow e zero regras: ele registra cada chamada de ferramenta no trilho de auditoria, mas não bloqueia nada. Descomente e edite policies (ou cole suas próprias regras) para começar a aplicar. Veja o Guia de Políticas para a sintaxe de regras.

O bloco abaixo é um alvo ilustrativo — não o arquivo que init escreve — mostrando políticas, orçamentos, auditoria e um segredo do dashboard:

version: '1'

upstream:
  url: 'http://localhost:8080/mcp' # Your existing MCP server
  transport: streamable-http # streamable-http (default), sse, or stdio

listen:
  port: 3000 # Helio listens here

session:
  identity: # Ordered identity sources; first match wins
    - source: header
      name: x-helio-session-id # Agent harnesses set this once per run
    - source: legacy_header # Verbatim Mcp-Session-Id (deprecation window)
  on_unresolved: deny # deny | anonymous

policies:
  default: allow

  # These rules match on tool-name globs (deny / rate-limit / spend-limit):
  rules:
    # Block destructive operations
    - match:
        tool: 'delete_*'
      action: deny
      feedback:
        message: 'Destructive operations are disabled'

    # Rate limit expensive API calls
    - match:
        tool: 'search_*'
      action: rate_limit
      limits:
        max_calls: 100
        window: 1h
        key: tool

    # Spend limit on payment tools
    - match:
        tool: 'create_payment'
      action: spend_limit
      limits:
        max_spend:
          field: '$.amount'
          limit: 5000
          currency: 'GBP'
          window: 24h

budgets:
  # One depleting pot shared by every tool that spends.
  - name: agent-payments
    limit: 50
    currency: USD
    window: session
    key: session
    on_exceed: deny # or require_approval for a break-glass ticket
    contributors:
      - match:
          tool: 'stripe_*'
        field: '$.amount'
      - match:
          tool: 'paypal_*'
        field: '$.total'

audit:
  storage: sqlite
  retention: 90d
  include_responses: true

dashboard:
  enabled: true
  port: 3100
  api_secret: '${HELIO_DASHBOARD_SECRET}'

Campos omitidos como listen.host, dashboard.host e audit.path caem para padrões seguros (127.0.0.1 para ambos os hosts — somente loopback — e ./helio-audit.db). A Referência de Configuração é a lista autoritativa de cada campo, seu padrão e a ordem canônica das seções.

Se o seu upstream exigir uma credencial estática (por exemplo, Authorization: Bearer … em um servidor MCP hospedado), defina upstream.headers — os valores suportam interpolação ${VAR} para que segredos fiquem fora do arquivo.

Sem servidor MCP para testar? O Helio inclui um servidor echo sem dependências que você pode rodar em um comando — veja o guia Começando.

Sobre dashboard.api_secret:

• Se você rodou npx @gethelio/proxy init, seu helio.yaml já contém o digest SHA-256 de um segredo gerado, e init imprimiu o segredo em si uma vez. Guarde o valor impresso; é com ele que você faz login. Pule este passo.

• Se você criou helio.yaml manualmente usando o placeholder ${HELIO_DASHBOARD_SECRET} mostrado acima, defina a variável antes de start:

  export HELIO_DASHBOARD_SECRET="$(openssl rand -hex 32)"
  

3. Iniciar o Helio

npx @gethelio/proxy start

4. Aponte seu agente para o Helio

{
  "mcpServers": {
    "my-tools": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Sem agente à mão? Você não precisa de um para ver o Helio funcionar. Aponte o MCP Inspector oficial para http://localhost:3000/mcp (rode npx @modelcontextprotocol/inspector, transporte: Streamable HTTP — o Inspector conecta através de seu próprio backend local, que não envia cabeçalho Origin; um Origin enviado pelo navegador é rejeitado por design), ou envie uma chamada direto pelo proxy a partir do terminal:

curl -s -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_weather","arguments":{"city":"London"}}}'

De qualquer forma, a chamada aparece no dashboard com sua decisão de política. (get_weather é uma das ferramentas de demonstração no servidor echo do Helio.)

5. Abra o dashboard

http://localhost:3100

Se solicitado, faça login com o segredo do dashboard que init imprimiu (o arquivo contém apenas seu digest).

É isso. Cada chamada de ferramenta agora passa pelo Helio com um trilho de auditoria completo, limites de taxa e controles de gastos.

Quer aprovações human-in-the-loop para operações de escrita? Veja docs/approvals.md para o fluxo completo de aprovação via Slack e dashboard, ou copie examples/slack-approvals/ como ponto de partida.

Recursos

Mecanismo de Políticas

Regras YAML declarativas que correspondem ao nome da ferramenta, anotações, parâmetros de entrada, ambiente e estado acumulado. Ações irreversíveis são sinalizadas, e o modo dry-run executa o pipeline completo sem encaminhar para o servidor MCP. Políticas recarregam a quente sem reiniciar.

policies:
  rules:
    - match:
        tool: 'create_payment'
        input:
          '$.amount': { gt: 1000 }
      action: require_approval

Orçamentos de Gastos Entre Ferramentas

Aplicação de gastos acumulados entre ferramentas: um único pote que se esgota agrega gastos de todas as ferramentas que o alimentam — Stripe e PayPal em um único limite, cada uma expondo o valor sob seu próprio campo de argumento. Determinístico no gate MCP, persistente entre reinicializações via um ledger de gastos durável, com aprovações break-glass para excedentes e uma visão ao vivo no dashboard.

budgets:
  - name: daily-cap
    limit: 50
    currency: USD
    window: 24h
    on_exceed: require_approval # a breach becomes a human decision
    contributors:
      - match:
          tool: 'stripe_*'
        field: '$.amount'
      - match:
          tool: 'paypal_*'
        field: '$.total'

Orçamentos governam ferramentas que expõem o que estão gastando em um campo de argumento. Assista ao fluxo completo — esgotamento ao vivo, violação, aprovação break-glass, o excedente aprovado chegando ao ledger — na demonstração de início rápido Docker ou no exemplo de orçamentos executável.

Fundamentação de Evidências

Exija prova antes de ações de alto risco. Um reembolso requer uma consulta de pedido anterior. Uma implantação requer uma execução de teste bem-sucedida. O SDK opcional marca saídas de ferramentas como evidência; o proxy aplica requisitos de evidência.

policies:
  rules:
    - match:
        tool: 'process_refund'
      action: deny
      evidence:
        requires: ['orders.lookup']

# Optional SDK enrichment
from helio import HelioContext

# Mark a tool output as evidence
with HelioContext() as ctx:
    result = orders.lookup(order_id)
    ctx.mark_evidence("orders.lookup", "order_data", result)

O SDK fala com o proxy pela API sideband (padrão 127.0.0.1:3200; o host de bind é configurável via sdk.host). Quando o sideband do SDK está habilitado (sdk.enabled: true, desligado por padrão), o proxy gera um token hex de 32 bytes novo a cada helio start e o imprime no stderr:

SDK sideband listening on http://127.0.0.1:3200
SDK token (generated per-boot HELIO_SDK_TOKEN; pass as HELIO_SDK_TOKEN env var to your SDK clients):
  3f9c2b...d8a1

Passe o mesmo valor para o processo do SDK via HELIO_SDK_TOKEN e o SDK anexa automaticamente Authorization: Bearer <token> a cada chamada sideband. O sideband também rejeita qualquer requisição que carregue um cabeçalho Origin não nulo, então um arquivo HTML local malicioso não pode falar com ele através de um navegador. Operadores que precisam de um token estável entre reinicializações podem definir HELIO_SDK_TOKEN explicitamente no ambiente do proxy — o proxy respeita um valor pré-definido em vez de regenerar um, e não o ecoa no stderr.

Feedback de Autocorreção

Quando o Helio bloqueia uma ação, ele retorna feedback estruturado explicando o que falhou e o que o agente deve fazer em seguida. Os agentes podem então se autocorrigir e tentar novamente.

{
  "blocked": true,
  "reason": "evidence_missing",
  "missing_evidence": ["orders.lookup"],
  "suggestion": "Call orders.lookup with the order ID before retrying"
}

Cadeias de Dependência de Ações

Declare ações pré-requisito na política. O proxy rastreia ações concluídas por sessão e bloqueia qualquer coisa onde os pré-requisitos não são atendidos.

policies:
  rules:
    - match:
        tool: 'process_refund'
      action: allow
      requires: ['orders.lookup', 'customer.verify']

Fluxos de Aprovação

Roteie ações sensíveis para Slack, webhook ou o dashboard do Helio. Timeout e escalonamento configuráveis, além de uma sobreposição break-glass somente no dashboard (API REST e interface do dashboard; não exposta como botão do Slack).

Limites de Taxa e Gastos

Limites de taxa por ferramenta e por sessão. Limites de gastos por regra que bloqueiam uma ferramenta correspondente em seu próprio teto — para um teto acumulado que abrange ferramentas, veja Orçamentos de Gastos Entre Ferramentas.

Trilho de Auditoria

Cada chamada de ferramenta registrada: timestamp, identidade do agente, nome da ferramenta, entradas, decisão de política, cadeia de evidências, status de aprovação, resposta downstream e latência. Dashboard pesquisável. Exportação para JSON ou CSV.

Como o Helio se Compara

A revisão 2026-07-28 do MCP tornou o protocolo em si sem estado: sem handshake, sem sessões de nível de protocolo, estado entre chamadas carregado como handles que o modelo passa entre ferramentas. Esse padrão funciona para estado de aplicação e falha para estado de governança, porque uma chave de orçamento que o modelo pode ver é uma chave de orçamento que o modelo pode mudar. O Helio mantém identidade de sessão, orçamentos e evidências no proxy, fora do contexto do agente, que é por que esses controles ainda significam algo depois que o protocolo parou de rastrear sessões. Veja protocolo sem estado, governança com estado.

	Helio	Obot	Cerbos	Integrado (Anthropic / OpenAI)	Framework (LangChain / CrewAI)
O que governa	Ações por chamada com estado entre chamadas	Quais ferramentas/MCPs são acessíveis	Decisões de autorização em nível de aplicação	Permissões de agente dentro de uma plataforma	Comportamento de agente dentro de um framework
Arquitetura	Proxy MCP fora do processo	Gateway MCP fora do processo	Sidecar / biblioteca	Dentro da plataforma	Dentro do framework
Código aberto	✅ Apache 2.0	✅ Apache 2.0	✅ Apache 2.0	❌	Varia
Tempo para valor	5 minutos	Depende da configuração	Horas	Integrado	Integrado
Sem alterações no código do agente	✅	✅	❌	✅ (dentro da plataforma)	❌
Governa agentes que você não criou	✅ Qualquer agente MCP	✅ Qualquer agente MCP	✅ (qualquer aplicativo)	❌ Apenas uma plataforma	❌ Apenas um framework
Fundamentação de evidências	✅ Acumulativa entre chamadas	❌	❌	❌	Limitada
Feedback de autocorreção	✅ Dicas de repetição estruturadas	❌	❌	❌	Limitada
Limites de gasto / taxa com estado	✅ Orçamentos entre ferramentas + limites por regra¹	Básico	❌	❌	Limitada
Fluxos de aprovação	✅ Slack, webhook, painel	✅	❌	Limitado	Limitado
Trilha de auditoria (incl. respostas downstream)	✅ Captura respostas MCP upstream	Logs de decisão	Logs de decisão	Telemetria da plataforma	Logs do framework

¹ Limites de taxa e gasto por regra, além de orçamentos nomeados entre ferramentas: reservas persistentes que diminuem, com aprovações de exceção para excedentes.

Funciona Com

O Helio funciona com qualquer agente ou framework compatível com MCP:

• Claude (Anthropic)
• ChatGPT (OpenAI)
• LangChain / LangGraph
• CrewAI
• AutoGen
• Agentes personalizados usando qualquer SDK de cliente MCP

Documentação

• Começando: Instale e configure em 5 minutos
• Referência de Configuração: Cada opção YAML explicada
• Guia de Políticas: Como escrever regras com exemplos
• Fluxos de Aprovação: Aprovações via Slack, webhook e painel
• Trilha de Auditoria: O que é registrado, como pesquisar, como exportar
• Executando o Helio como Sidecar: Implante ao lado de um agente de codificação ou contêiner de desenvolvimento, com o upstream e a configuração fora de seu alcance e o Helio fora de sua rede
• Executando o Helio como seu próprio usuário: O nível de usuário separado no Ubuntu 24.04, executado de ponta a ponta

Exemplos

Configurações prontas para padrões comuns:

• Básico: Negue operações destrutivas, permita todo o resto
• Aprovações via Slack: Roteie ações destrutivas para o Slack
• Limites de Gasto: Governa o uso de ferramentas de pagamento
• Orçamentos: Um orçamento entre ferramentas para ferramentas Stripe e PayPal, com aprovações de exceção para excedentes, emparelhado com um limite de categoria que só cobra chamadas que declaram sua categoria de gasto
• Multi-Upstream: Dois upstreams nomeados atrás de um proxy, com limite de taxa e orçamento com escopo de porta

Contribuindo

Aceitamos contribuições. Veja CONTRIBUTING.md para instruções de configuração, padrões de codificação e processo de PR.

Boas primeiras issues estão marcadas como good-first-issue.

Comunidade

• GitHub Issues: Relatórios de bugs e solicitações de recursos
• Twitter/X: Atualizações e anúncios

Licença

Apache 2.0 - veja LICENSE.