Helio MCP Governance Proxy

Se sitúa entre tus agentes de IA y sus servidores MCP, y gobierna cada llamada de herramienta: reglas de política, límites de gasto entre servidores, aprobación humana para acciones riesgosas y un registro de auditoría completo. Sin cambios en el código del agente ni en los servidores MCP.

GitHub

Prueba este MCPPatrocinado

Documentación

Helio

Proxy de gobernanza de código abierto para agentes de IA

Primeros pasos · Documentación · Contribuir

Helio es un proxy MCP que se sitúa entre tus agentes de IA y las herramientas que utilizan. Cada llamada a una herramienta pasa por Helio, que aplica políticas, verifica evidencia, enruta aprobaciones, limita el gasto acumulado y registra todo — sin cambiar el código de tu agente ni tus servidores MCP.

npx @gethelio/proxy init

@gethelio/proxy es el único paquete de Node que instalas. Incluye el runtime del proxy y los recursos de interfaz del dashboard empaquetados juntos.

¿Por qué Helio?

Tu agente acaba de llamar a una API que no esperabas. Gastó dinero que no autorizaste. Modificó un registro de producción que no puedes deshacer fácilmente.

Los proveedores de modelos están construyendo gobernanza para sus propias plataformas, pero tus agentes se ejecutan en Claude, ChatGPT, LangChain, CrewAI y frameworks personalizados. Ninguna plataforma única gobierna el panorama completo. Y ninguna gobierna lo que sucede en sistemas posteriores como Stripe, Salesforce o GitHub.

Helio gobierna lo que los agentes hacen al resto del mundo a través de cualquier agente compatible con MCP, cualquier herramienta, cualquier plataforma.

Una regla en Helio no puede olvidarse ni debilitarse silenciosamente. No está en el contexto del modelo, por lo que una sesión larga no puede expulsarla y una inyección no puede discutirla, y la aplicación está en la ruta en lugar de en el prompt: una llamada a una herramienta enrutada a través de Helio se decide antes de reenviarse, sin importar lo que se le haya dicho al modelo. Cada intento de recargar el archivo de políticas, incluido uno que elimine una regla, es un registro de auditoría, y cada registro lleva el hash de la configuración vigente cuando se escribió, por lo que un cambio se muestra frente a las decisiones tomadas bajo ella. La afirmación de "no puede debilitarse silenciosamente" tiene una condición, indicada en Grados de aplicación.

Cómo funciona

MCP clients send tool calls through Helio — which applies its policy engine, evidence grounding, approval workflows, cross-tool spend budgets, rate and spend limits, audit trail, and self-repair feedback — before forwarding them to MCP servers. An optional thin Python SDK connects to Helio over a sideband.

Dos rutas de integración:

Solo proxy: Apunta tu cliente MCP a Helio en lugar de a tu servidor MCP. Cero cambios de código. Gobernanza inmediata.
Proxy + SDK: Añade el SDK delgado de Python para anotar llamadas a herramientas con contexto de evidencia y dependencias de acciones. Gobernanza más rica, en menos de 500 líneas de código.

Grados de aplicación

Helio gobierna en el grado más fuerte que cada ruta permite físicamente y lo registra por llamada:

Estructural (stdio MCP) — Helio posee el proceso hijo que generó, por lo que nada en la ruta MCP lo rodea; un proceso co-ubicado que pueda ejecutar la misma línea de comandos está fuera de este grado (ver la nota a continuación).
Red (HTTP MCP) — estructural si controlas la salida del upstream.
Aplicado por host (adaptadores de hook a través de la API de adaptadores, p. ej. OpenClaw) — para frameworks que ejecutan herramientas en proceso y exponen hooks en lugar de un transporte MCP. La puerta de hooks del framework aplica; Helio decide. Este es un grado cooperativo, más bajo que la ruta del proxy, y Helio lo etiqueta como tal en lugar de sobredeclararlo. Las decisiones de Helio aún no pueden expulsarse del contexto del agente ni inyectarse por prompt, y cualquier intento de rodearlas es visible en el registro de auditoría.

Los tres grados asumen que la configuración, el secreto y el almacén de auditoría del proxy están fuera del alcance del agente. En la instalación local predeterminada no lo están: el proxy se ejecuta como el mismo usuario que el agente. SECURITY.md establece el límite y los despliegues que lo cierran. Esa instalación también es la condición de "no puede debilitarse silenciosamente": un agente del mismo usuario puede reiniciar el proxy sin el pin de configuración y puede editar o eliminar el archivo de auditoría, por lo que el registro de recarga y el hash en cada registro son duraderos solo mientras el agente no pueda escribir el archivo de auditoría, y el flujo de eventos y stderr son los canales que salen de la caja antes de eso. Ejecuta el proxy como su propio usuario o en su propio contenedor, como hacen las recetas allí, y la condición desaparece.

Inicio rápido (5 minutos)

1. Instalar

npx @gethelio/proxy init

Este paquete único incluye el bundle de interfaz del dashboard integrado.

¿Ejecutas tu agente en un contenedor? npx @gethelio/proxy init --sandbox escribe el diseño de sidecar en su lugar; consulta Ejecutar Helio como Sidecar.

2. Configurar

npx @gethelio/proxy init ya creó un helio.yaml en la raíz de tu proyecto. Ábrelo (p. ej. nano helio.yaml, o en tu editor) y apunta upstream.url a tu servidor MCP existente. La forma singular upstream: sigue siendo totalmente compatible; para gobernar más de un servidor MCP, declara una lista con nombre upstreams: en su lugar (establece exactamente uno de los dos). Los conjuntos de herramientas nunca se fusionan: cada upstream con nombre se sirve en su propia puerta /mcp/<name>. Consulta la Referencia de configuración.

Aviso — Helio se inicia en modo solo auditoría. init genera la sección policies comentada, por lo que de fábrica Helio se ejecuta con default: allow y cero reglas: registra cada llamada a herramienta en el registro de auditoría pero no bloquea nada. Descomenta y edita policies (o pega tus propias reglas) para comenzar a aplicar. Consulta la Guía de políticas para la sintaxis de reglas.

El bloque a continuación es un objetivo ilustrativo — no el archivo que escribe init — que muestra políticas, presupuestos, auditoría y un secreto del 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}'

Los campos omitidos como listen.host, dashboard.host y audit.path recurren a valores predeterminados seguros (127.0.0.1 para ambos hosts — solo loopback — y ./helio-audit.db). La Referencia de configuración es la lista autoritativa de cada campo, su valor predeterminado y el orden canónico de secciones.

Si tu upstream requiere una credencial estática (por ejemplo Authorization: Bearer … en un servidor MCP alojado), establece upstream.headers — los valores admiten interpolación ${VAR} para que los secretos no queden en el archivo.

¿No tienes un servidor MCP para probar? Helio incluye un servidor echo sin dependencias que puedes ejecutar con un comando — consulta la Guía de primeros pasos.

Acerca de dashboard.api_secret:

Si ejecutaste npx @gethelio/proxy init, tu helio.yaml ya contiene el digest SHA-256 de un secreto generado, y init imprimió el secreto una vez. Conserva el valor impreso; es con lo que inicias sesión. Omite este paso.
Si redactaste helio.yaml manualmente usando el marcador de posición ${HELIO_DASHBOARD_SECRET} mostrado arriba, establece la variable antes de start:
```
export HELIO_DASHBOARD_SECRET="$(openssl rand -hex 32)"
```

3. Iniciar Helio

npx @gethelio/proxy start

4. Apunta tu agente a Helio

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

¿No tienes un agente a mano? No necesitas uno para ver Helio funcionar. Apunta el Inspector MCP oficial a http://localhost:3000/mcp (ejecuta npx @modelcontextprotocol/inspector, transporte: Streamable HTTP — el Inspector se conecta a través de su propio backend local, que no envía el encabezado Origin; un Origin enviado por navegador se rechaza por diseño), o envía una llamada directamente a través del proxy desde la 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 cualquier manera, la llamada aparece en el dashboard con su decisión de política. (get_weather es una de las herramientas de demostración en el servidor echo de Helio).

5. Abrir el dashboard

http://localhost:3100

Si se te solicita, inicia sesión con el secreto del dashboard que imprimió init (el archivo solo contiene su digest).

Eso es todo. Cada llamada a herramienta ahora pasa por Helio con un registro de auditoría completo, límites de tasa y controles de gasto.

¿Quieres aprobaciones humanas en el circuito para operaciones de escritura? Consulta docs/approvals.md para el flujo completo de aprobaciones de Slack y dashboard, o copia examples/slack-approvals/ como punto de partida.

Características

Motor de políticas

Reglas YAML declarativas que coinciden con el nombre de la herramienta, anotaciones, parámetros de entrada, entorno y estado acumulado. Las acciones irreversibles se marcan, y el modo de prueba en seco ejecuta el pipeline completo sin reenviar al servidor MCP. Las políticas se recargan en caliente sin reiniciar.

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

Presupuestos de gasto entre herramientas

Aplicación de gasto acumulado entre herramientas: un fondo único que se agota agrega el gasto de cada herramienta que lo alimenta — Stripe y PayPal en un solo límite, cada uno exponiendo el monto bajo su propio campo de argumento. Determinista en la puerta MCP, persistente entre reinicios mediante un libro de gasto duradero, con aprobaciones de ruptura para excesos y una vista en vivo en el 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'

Los presupuestos gobiernan herramientas que exponen lo que gastan en un campo de argumento. Observa el flujo completo — agotamiento en vivo, incumplimiento, aprobación de ruptura, el exceso aprobado llegando al libro — en la demo de inicio rápido de Docker o en el ejemplo de presupuestos ejecutable.

Fundamentación de evidencia

Requiere prueba antes de acciones de alto riesgo. Un reembolso requiere una consulta previa de pedido. Un despliegue requiere una ejecución de pruebas exitosa. El SDK opcional marca las salidas de herramientas como evidencia; el proxy aplica los requisitos de evidencia.

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)

El SDK habla con el proxy a través de la API de sideband (por defecto 127.0.0.1:3200; el host de enlace es configurable mediante sdk.host). Cuando el sideband del SDK está habilitado (sdk.enabled: true, desactivado por defecto), el proxy genera un token hex nuevo de 32 bytes en cada helio start y lo imprime en 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

Pasa el mismo valor al proceso del SDK mediante HELIO_SDK_TOKEN y el SDK adjunta automáticamente Authorization: Bearer <token> a cada llamada de sideband. El sideband también rechaza cualquier solicitud que lleve un encabezado Origin no nulo, por lo que un archivo HTML local malicioso no puede comunicarse con él a través de un navegador. Los operadores que necesiten un token estable entre reinicios pueden establecer HELIO_SDK_TOKEN explícitamente en el entorno del proxy — el proxy respeta un valor preestablecido en lugar de regenerar uno, y no lo repite en stderr.

Retroalimentación de auto-reparación

Cuando Helio bloquea una acción, devuelve retroalimentación estructurada que explica qué falló y qué debería hacer el agente a continuación. Los agentes pueden entonces autocorregirse y reintentar.

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

Cadenas de dependencia de acciones

Declara acciones prerrequisito en la política. El proxy rastrea acciones completadas por sesión y bloquea cualquier cosa donde los prerrequisitos no se cumplan.

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

Flujos de aprobación

Enruta acciones sensibles a Slack, webhook o al dashboard de Helio. Tiempo de espera y escalamiento configurables, más una anulación de ruptura solo para dashboard (API REST y UI del dashboard; no expuesta como botón de Slack).

Límites de tasa y gasto

Límites de tasa por herramienta y por sesión. Límites de gasto por regla que bloquean una herramienta coincidente en su propio tope — para un tope acumulativo que abarque herramientas, consulta Presupuestos de gasto entre herramientas.

Registro de auditoría

Cada llamada a herramienta registrada: marca de tiempo, identidad del agente, nombre de la herramienta, entradas, decisión de política, cadena de evidencia, estado de aprobación, respuesta posterior y latencia. Dashboard con búsqueda. Exportación a JSON o CSV.

Cómo se compara Helio

La revisión MCP 2026-07-28 hizo que el protocolo en sí fuera sin estado: sin handshake, sin sesiones a nivel de protocolo, estado entre llamadas transportado como manejadores que el modelo pasa entre herramientas. Ese patrón funciona para estado de aplicación y falla para estado de gobernanza, porque una clave de presupuesto que el modelo puede ver es una clave de presupuesto que el modelo puede cambiar. Helio mantiene la identidad de sesión, presupuestos y evidencia en el proxy, fuera del contexto del agente, que es por lo que esos controles siguen significando algo después de que el protocolo dejó de rastrear sesiones. Consulta protocolo sin estado, gobernanza con estado.

	Helio	Obot	Cerbos	Integrado (Anthropic / OpenAI)	Framework (LangChain / CrewAI)
Qué gobierna	Acciones por llamada con estado entre llamadas	Qué herramientas/MCPs son accesibles	Decisiones de autorización a nivel de aplicación	Permisos de agentes dentro de una plataforma	Comportamiento de agentes dentro de un framework
Arquitectura	Proxy MCP fuera de proceso	Puerta de enlace MCP fuera de proceso	Sidecar / biblioteca	Dentro de la plataforma	Dentro del framework
Código abierto	✅ Apache 2.0	✅ Apache 2.0	✅ Apache 2.0	❌	Varía
Tiempo para obtener valor	5 minutos	Depende de la configuración	Horas	Integrado	Integrado
Sin cambios en el código del agente	✅	✅	❌	✅ (dentro de la plataforma)	❌
Gobierna agentes que no construiste	✅ Cualquier agente MCP	✅ Cualquier agente MCP	✅ (cualquier aplicación)	❌ Solo una plataforma	❌ Solo un framework
Fundamentación de evidencia	✅ Acumulativa entre llamadas	❌	❌	❌	Limitada
Retroalimentación de auto-reparación	✅ Sugerencias estructuradas de reintento	❌	❌	❌	Limitada
Límites de gasto / tasa con estado	✅ Presupuestos entre herramientas + límites por regla¹	Básico	❌	❌	Limitada
Flujos de aprobación	✅ Slack, webhook, panel	✅	❌	Limitada	Limitada
Registro de auditoría (incl. respuestas posteriores)	✅ Captura respuestas MCP ascendentes	Registros de decisiones	Registros de decisiones	Telemetría de plataforma	Registros del framework

¹ Límites de tasa y gasto por regla, más presupuestos nombrados entre herramientas: fondos persistentes que se agotan con aprobaciones de ruptura para excesos.

Funciona Con

Helio funciona con cualquier agente o framework compatible con MCP:

Claude (Anthropic)
ChatGPT (OpenAI)
LangChain / LangGraph
CrewAI
AutoGen
Agentes personalizados que usen cualquier SDK de cliente MCP

Documentación

Primeros pasos: Instala y configura en 5 minutos
Referencia de configuración: Cada opción de YAML explicada
Guía de políticas: Cómo escribir reglas con ejemplos
Flujos de aprobación: Aprobaciones por Slack, webhook y panel
Registro de auditoría: Qué se registra, cómo buscar, cómo exportar
Ejecutar Helio como sidecar: Despliega junto a un agente de codificación o contenedor de desarrollo con el upstream y la configuración fuera de su alcance y Helio fuera de su red
Ejecutar Helio como su propio usuario: El nivel de usuario separado en Ubuntu 24.04, ejecutado de extremo a extremo

Ejemplos

Configuraciones listas para patrones comunes:

Básico: Deniega operaciones destructivas, permite todo lo demás
Aprobaciones por Slack: Enruta acciones destructivas a Slack
Límites de gasto: Gobierna el uso de herramientas de pago
Presupuestos: Un presupuesto entre herramientas para Stripe y PayPal con aprobaciones de exceso de ruptura, junto con un tope de categoría que solo cobra llamadas que declaran su categoría de gasto
Multi-upstream: Dos upstreams nombrados detrás de un proxy, con un límite de tasa y presupuesto con alcance de puerta

Contribuciones

Agradecemos las contribuciones. Consulta CONTRIBUTING.md para instrucciones de configuración, estándares de codificación y proceso de PR.

Los primeros problemas buenos están etiquetados como good-first-issue.

Comunidad

Problemas de GitHub: Informes de errores y solicitudes de funciones
Twitter/X: Actualizaciones y anuncios

Licencia

Apache 2.0 - consulta LICENSE.