Agent Gateway

Una puerta de enlace local de agente orientada a producción que proporciona a ChatGPT Web (GPT-5.6 Sol) acceso determinista a tu máquina local a través del Model Context Protocol (MCP) sobre Streamable HTTP.

El modo directo es la arquitectura predeterminada. La puerta de enlace expone herramientas MCP precisas y deterministas (filesystem, search, process, git) que se ejecutan dentro de directorios autorizados por el operador. GPT-5.6 Sol es el único agente de razonamiento: es dueño del bucle de planificación y decisión, y la puerta de enlace ejecuta sus llamadas a herramientas — la puerta de enlace nunca invoca un segundo LLM. La puerta de enlace funciona sin servidor OpenCode y sin modelo/proveedor configurado.

El modo agente OpenCode opcional (deshabilitado por defecto) delega además tareas completas a un agente local OpenCode para trabajos autónomos más largos.

ChatGPT Web (GPT-5.6 Sol)  <-- the reasoning agent
        │
        │  MCP over HTTPS (Streamable HTTP)
        ▼
Cloudflare Quick Tunnel
        │
        ▼
Agent Gateway  http://127.0.0.1:8000/mcp
        │
        ├── Direct mode (default): deterministic tools
        │       workspace_open / file_* / code_search / process_run / git_*
        │       (filesystem, search, process, git — no OpenCode, no LLM)
        │
        └── OpenCode agent mode (optional, ENABLE_OPENCODE_AGENT=true)
                agent_start_task / agent_status / agent_messages / agent_diff
                → OpenCode  http://127.0.0.1:4096  (localhost only)
        │
        ▼
Local system / repositories / tools

Este proyecto sustituye al prototipo anterior chatgpt-local-repo-mcp por una base limpia, probada y extensible. No es una copia de ese prototipo.

Por qué una puerta de enlace

• ChatGPT no puede acceder a tu localhost. Un endpoint MCP tunelizado es el puente verificado.

• Las herramientas directas y deterministas superan a un segundo agente. Para la mayoría del trabajo con archivos, búsquedas, procesos y git, las primitivas de la puerta de enlace son exactas, rápidas y no necesitan un modelo adicional. GPT-5.6 Sol conserva el razonamiento; la puerta de enlace conserva la máquina.

• Puedes crecer. OpenCode (o un futuro adaptador de Codex/Claude Code) puede habilitarse detrás de la misma interfaz MCP estable para la delegación autónoma de tareas.

Related MCP server: chatgpt-codex-tools-mcp

Límites de confianza

El endpoint /mcp de la puerta de enlace es la única superficie pública. Los llamadores remotos no pueden:

• acceder a directorios fuera de las raíces permitidas configuradas,

• ejecutar comandos de shell sin restricciones (los comandos son opcionales mediante AGENT_ENABLE_COMMANDS y están limitados en el tiempo),

• delegar tareas a OpenCode a menos que el operador haya habilitado ese modo,

• autoaprobar sus propias solicitudes de permiso (nunca implementado),

• alcanzar la puerta de enlace sin el token portador cuando AGENT_GATEWAY_TOKEN está configurado.

Arquitectura

tools/  (MCP tools)            thin, callable by GPT-5.6 Sol
   │
   ├── tools/direct.py         deterministic primitives (default mode)
   │       workspace_open → workspace_tree / file_read / file_stat /
   │       file_find / code_search / file_write / file_replace /
   │       file_apply_patch / process_run / git_status / git_diff /
   │       git_log / git_show
   │
   ├── workspaces/             WorkspaceManager: opaque ws_ IDs bound to
   │                           allowed roots; every path re-validated
   │
   └── services/delegation.py  OpenCode mode: session lifecycle + registry
           │
           ▼
       executors/base.py       Executor interface (health, sessions, prompts,
           │                   status, messages, diffs, abort, permissions)
           ▼
       executors/opencode/     OpenCodeExecutor → OpenCodeClient → HTTP API

Cada módulo depende de la capa inferior; las herramientas MCP nunca tocan httpx directamente.

Herramientas MCP — Modo directo (predeterminado, sin OpenCode, sin modelo)

Las herramientas directas están disponibles siempre que la puerta de enlace esté en ejecución. Solo operan dentro de espacios de trabajo abiertos mediante workspace_open (que requiere que el directorio esté dentro de AGENT_ALLOWED_ROOTS).

Todas las herramientas directas: rutas validadas (sin rutas absolutas, sin .., sin escapes de enlaces simbólicos), límites de tamaño en lecturas, límites de entradas en listados, argumentos estrictos de ruta relativa dentro del espacio de trabajo vinculado.

Bucle del modo directo (tal como lo usa ChatGPT)

workspace_open("C:\...\project")
   → ws_abc123
file_read(ws_abc123, "src/main.py")          → current content
file_apply_patch(ws_abc123, "src/main.py", <<<diff>>>)   → patch applied
process_run(ws_abc123, executable="pytest", args=["-q"], timeout_seconds=60) → verification
git_diff(ws_abc123)                           → review the change set

Herramientas MCP — Modo agente OpenCode (opcional)

Habilitado solo con ENABLE_OPENCODE_AGENT=true. Añade el ciclo de vida genérico de delegación más los diagnósticos de OpenCode:

Ciclo de vida de la delegación

agent_start_task(executor, task, directory)
      │
      ▼  returns session ID immediately (async dispatch)
agent_status(session_id)
      │
      ├── busy / retry   → wait and poll again
      │
      └── idle + completed
            ├── agent_messages(session_id)   → read what the agent did
            ├── agent_diff(session_id)        → review file changes
            ├── agent_continue(session_id, followup)  → keep going
            └── agent_abort(session_id)       → stop runaway work

El trabajo de agente de larga duración utiliza la API de prompt asíncrono de OpenCode (POST /session/{id}/prompt_async). La puerta de enlace responde inmediatamente y nunca mantiene abierta una solicitud MCP mientras el agente trabaja. La finalización se informa solo cuando la sesión está inactiva y el último turno del asistente terminó con finish="stop".

Cada operación sobre una sesión existente vuelve a verificar que el directorio real de la sesión sigue dentro de AGENT_ALLOWED_ROOTS (cierre seguro).

Flujo de trabajo de permisos

La puerta de enlace nunca autoaprueba. Cuando el agente necesita aprobación, genera una solicitud de permiso; el supervisor la ve mediante agent_status / agent_pending_permissions, y un humano decide mediante agent_reply_permission. Respuestas permitidas: once, always, reject.

Modelo de seguridad

• Autenticación de transporte: cuando AGENT_GATEWAY_TOKEN está configurado, cada solicitud a /mcp debe incluir Authorization: Bearer <token> (comparación en tiempo constante). Las solicitudes sin un token válido reciben 401. También se requiere un token cuando MCP_HOST es una dirección que no es de loopback (p. ej. 0.0.0.0, IP de LAN) para evitar una exposición pública accidental.

• Seguridad de directorios: AGENT_ALLOWED_ROOTS es una lista separada por punto y coma de rutas absolutas. Si no está configurada, se rechaza todo directorio (cierre seguro). Cada candidato se canonicaliza, debe existir (para raíces de tareas), no debe ser una raíz del sistema de archivos y debe estar dentro de una raíz permitida. Se rechazan el traversal, los escapes de enlaces simbólicos y la suplantación por prefijo hermano (sample vs sample-evil); las comparaciones no distinguen mayúsculas/minúsculas en Windows.

• Sin shell sin restricciones por defecto: process_run requiere AGENT_ENABLE_COMMANDS=true y aplica un tiempo de espera (300 s por defecto).

• E/S limitada: el tamaño de lectura, las entradas de árbol, los resultados de búsqueda y la salida de procesos están limitados; los payloads enormes se truncan en lugar de transmitirse sin límite.

• El modo OpenCode es opcional (ENABLE_OPENCODE_AGENT=true); sin él, las herramientas agent_* no se registran y no se contacta con ningún backend.

• Los permisos nunca se autoaprueban en el modo OpenCode.

• Red: OpenCode permanece solo en localhost. Solo /mcp se tuneliza. PUBLIC_MCP_HOST incluye en la lista blanca el host del túnel mientras mantiene habilitada la protección contra el reenlace de DNS.

• Secretos: las contraseñas y las cabeceras Authorization nunca se registran; el resumen de configuración enmascara la contraseña; las listas de modelos de proveedores excluyen las claves.

Instalación

Requisitos: Python 3.11+ (probado en 3.14), git. La CLI de OpenCode solo es necesaria para el modo OpenCode opcional.

cd C:\Users\dev\Desktop\chatgpt-like\chatgpt-agent-gateway
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Configuración

Copia .env.example a .env y edítalo, o configura las variables de entorno directamente:

$env:MCP_PORT = "8000"
$env:PUBLIC_MCP_HOST = "your-tunnel.trycloudflare.com"   # optional
$env:AGENT_ALLOWED_ROOTS = "C:\Users\dev\Desktop\sample-repo;C:\Users\dev\Desktop\projects"
$env:AGENT_GATEWAY_TOKEN = "generate-a-long-random-token"   # recommended
$env:AGENT_ENABLE_COMMANDS = "true"   # allow process_run
$env:LOG_LEVEL = "INFO"

Ejecutar la puerta de enlace

agent-gateway
# or
python -m agent_gateway.server

Endpoint MCP local: http://127.0.0.1:8000/mcp

Exposición a través de Cloudflare

La seguridad de transporte de la puerta de enlace mantiene habilitada la protección contra el secuestro de DNS y permite localhost más el nombre de host que establezcas en PUBLIC_MCP_HOST. Inicia un Quick Tunnel que apunte a http://127.0.0.1:8000:

cloudflared tunnel --url http://127.0.0.1:8000

Toma la https://<id>.trycloudflare.com impresa, establécela como PUBLIC_MCP_HOST y reinicia la puerta de enlace. Establece AGENT_GATEWAY_TOKEN — la puerta de enlace se niega a exponer un /mcp sin token públicamente a menos que establezcas explícitamente AGENT_INSECURE_NO_TOKEN_OPT_OUT=true. Las comprobaciones de seguridad nunca se deshabilitan para que el túnel funcione; el host público se incluye explícitamente en la lista de permitidos.

Ejecutar OpenCode (modo agente opcional)

opencode serve --port 4096 --hostname 127.0.0.1

Verifica: Invoke-RestMethod http://127.0.0.1:4096/global/health

Pruebas

pytest                     # default suite: direct mode only (150 passed, 9 skipped)
pytest tests/unit          # unit tests — no services needed
$env:ENABLE_OPENCODE_AGENT = "true"
pytest                     # full suite incl. OpenCode mode (158 passed, 1 skipped)

El conjunto de pruebas e2e inicia un proceso de puerta de enlace real en un puerto temporal y lo controla mediante MCP sobre HTTP con el protocolo exacto que usa ChatGPT. Dos variantes:

• tests/e2e/test_direct_e2e.py — modo directo sin OpenCode y sin modelo: 401 sin token, lista de herramientas, espacio de trabajo → leer → parchear → escribir → proceso → git diff, y rechazo de directorios no autorizados. Se ejecuta en el conjunto predeterminado.

• tests/e2e/test_opencode_e2e.py — modo OpenCode (condicionado a ENABLE_OPENCODE_AGENT=true y un servidor activo): tarea delegada de solo lectura (repositorio verificado byte por byte sin modificar) más el flujo completo del protocolo MCP, incluidos los casos de error.

Estructura del repositorio

src/agent_gateway/
├── config.py            typed configuration (env-driven, validated)
├── errors.py            gateway error taxonomy
├── logging.py           redacted logging
├── security/
│   ├── paths.py         allowed-roots enforcement
│   └── auth.py          bearer-token middleware (constant-time compare)
├── workspaces/          WorkspaceManager: ws_ IDs, per-workspace validation
├── direct/              deterministic primitives (filesystem, search,
│   │                    process, git) shared by the direct tools
├── executors/
│   ├── base.py          Executor interface
│   └── opencode/        OpenCode client, models, errors, executor
├── services/delegation.py  OpenCode orchestration + session registry
├── tools/               MCP tool registration (direct, gateway, delegation,
│   │                    permissions, opencode)
└── server.py            MCP server assembly + entry point

Arquitectura futura del ejecutor

Añade un nuevo backend implementando executors/base.py, registrándolo en executors/__init__.py y añadiendo cualquier herramienta de diagnóstico específica del backend en tools/. Las herramientas genéricas agent_* y el servicio de delegación no requieren cambios. No se incluyen adaptadores falsos de Codex/Claude.

Limitaciones

• El registro de sesiones de OpenCode está en memoria; un reinicio de la puerta de enlace olvida de qué directorios provienen las sesiones (OpenCode en sí persiste las sesiones por ID).

• Los espacios de trabajo en modo directo (ws_...) también caducan al reiniciar la puerta de enlace; vuelve a abrirlos con workspace_open.

• file_apply_patch requiere coincidencias de contexto exactas; no hay aplicación difusa.

• La API de OpenCode se consume como un superconjunto de las rutas OpenAPI v1; las versiones futuras del backend deben volver a verificarse con su propio /doc.

• La respuesta de permiso always se admite a nivel de protocolo; los operadores pueden querer deshabilitarla globalmente para imponer aprobaciones por ejecución.