Agent Gateway

A production-oriented local agent gateway that gives ChatGPT Web (GPT-5.6 Sol) deterministic access to your local machine through the Model Context Protocol (MCP) over Streamable HTTP.

Direct mode is the default architecture. The gateway exposes precise, deterministic MCP tools (filesystem, search, process, git) that run inside operator-authorized directories. GPT-5.6 Sol is the only reasoning agent: it owns the planning and decision loop, and the gateway executes its tool calls — no second LLM is ever invoked by the gateway. The gateway works with no OpenCode server and no model/provider configured.

Optional OpenCode agent mode (disabled by default) additionally delegates whole tasks to a local OpenCode agent for longer, autonomous work.

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

This project replaces the earlier chatgpt-local-repo-mcp prototype with a clean, tested, extensible foundation. It is not a copy of that prototype.

Why a gateway

• ChatGPT cannot reach your localhost. A tunneled MCP endpoint is the verified bridge.

• Direct deterministic tools beat a second agent. For most file, search, process, and git work, the gateway's primitives are exact, fast, and need no extra model. GPT-5.6 Sol keeps the reasoning; the gateway keeps the machine.

• You can grow. OpenCode (or a future Codex/Claude Code adapter) can be enabled behind the same stable MCP interface for autonomous task delegation.

Related MCP server: chatgpt-codex-tools-mcp

Trust boundaries

The gateway's /mcp endpoint is the only public surface. Remote callers cannot:

• access directories outside the configured allowed roots,

• run unrestricted shell commands (commands are opt-in via AGENT_ENABLE_COMMANDS and time-bounded),

• delegate tasks to OpenCode unless the operator enabled that mode,

• auto-approve their own permission requests (never implemented),

• reach the gateway without the bearer token when AGENT_GATEWAY_TOKEN is set.

Architecture

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

Every module depends on the layer below it; the MCP tools never touch httpx directly.

MCP tools — Direct mode (default, no OpenCode, no model)

The direct tools are available whenever the gateway runs. They only operate inside workspaces opened via workspace_open (which requires the directory to be inside AGENT_ALLOWED_ROOTS).

All direct tools: validated paths (no absolute paths, no .., no symlink escapes), size caps on reads, entry caps on listings, strict relative-path arguments inside the bound workspace.

Direct-mode loop (as ChatGPT uses it)

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

MCP tools — OpenCode agent mode (optional)

Enabled only with ENABLE_OPENCODE_AGENT=true. Adds the generic delegation lifecycle plus OpenCode diagnostics:

Delegation lifecycle

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

Long-running agent work uses OpenCode's async prompt API (POST /session/{id}/prompt_async). The gateway returns immediately and never holds an MCP request open while the agent works. Completion is reported only when the session is idle and the last assistant turn finished with finish="stop".

Every operation on an existing session re-verifies that the session's real directory is still inside AGENT_ALLOWED_ROOTS (fail closed).

Permission workflow

The gateway never auto-approves. When the agent needs approval it raises a permission request, the supervisor sees it via agent_status / agent_pending_permissions, and a human decides via agent_reply_permission. Allowed replies: once, always, reject.

Security model

• Transport auth: when AGENT_GATEWAY_TOKEN is set, every request to /mcp must carry Authorization: Bearer <token> (constant-time compare). Requests without a valid token get 401. A token is also required when MCP_HOST is a non-loopback address (e.g. 0.0.0.0, LAN IP) to prevent accidental public exposure.

• Directory security: AGENT_ALLOWED_ROOTS is a semicolon-separated list of absolute paths. If unset, every directory is rejected (fail closed). Each candidate is canonicalized, must exist (for task roots), must not be a filesystem root, and must sit inside an allowed root. Traversal, symlink escapes, and sibling-prefix spoofing (sample vs sample-evil) are rejected; comparisons are case-insensitive on Windows.

• No unrestricted shell by default: process_run requires AGENT_ENABLE_COMMANDS=true and enforces a timeout (default 300 s).

• Bounded I/O: read size, tree entries, search results, and process output are capped; huge payloads are truncated instead of streamed unbounded.

• OpenCode mode is opt-in (ENABLE_OPENCODE_AGENT=true); without it the agent_* tools are not registered and no backend is contacted.

• Permissions never auto-approved in OpenCode mode.

• Network: OpenCode stays localhost-only. Only /mcp is tunneled. PUBLIC_MCP_HOST allow-lists the tunnel host while keeping DNS-rebinding protection enabled.

• Secrets: passwords and Authorization headers are never logged; the config summary masks the password; provider model lists exclude keys.

Installation

Requirements: Python 3.11+ (tested on 3.14), git. OpenCode CLI is only needed for the optional OpenCode mode.

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

Configuration

Copy .env.example to .env and edit, or set environment variables directly:

$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"

Running the gateway

agent-gateway
# or
python -m agent_gateway.server

Local MCP endpoint: http://127.0.0.1:8000/mcp

Exposing via Cloudflare

The gateway's transport security keeps DNS-rebinding protection enabled and allows localhost plus the hostname you set in PUBLIC_MCP_HOST. Start a Quick Tunnel pointing at http://127.0.0.1:8000:

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

Take the printed https://<id>.trycloudflare.com, set it as PUBLIC_MCP_HOST, then restart the gateway. Set AGENT_GATEWAY_TOKEN — the gateway refuses to expose a tokenless /mcp publicly unless you explicitly set AGENT_INSECURE_NO_TOKEN_OPT_OUT=true. Security checks are never disabled to make the tunnel work; the public host is explicitly allow-listed instead.

Running OpenCode (optional agent mode)

opencode serve --port 4096 --hostname 127.0.0.1

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

Testing

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)

The e2e suite starts a real gateway process on a temporary port and drives it over MCP-over-HTTP with the exact protocol ChatGPT uses. Two flavors:

• tests/e2e/test_direct_e2e.py — direct mode with no OpenCode and no model: 401 without token, tool list, workspace → read → patch → write → process → git diff, and rejection of unauthorized directories. Runs in the default suite.

• tests/e2e/test_opencode_e2e.py — OpenCode mode (gated on ENABLE_OPENCODE_AGENT=true and a live server): read-only delegated task (repository verified byte-for-byte unmodified) plus the full MCP protocol flow including error cases.

Repository layout

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

Future executor architecture

Add a new backend by implementing executors/base.py, registering it in executors/__init__.py, and adding any backend-specific diagnostic tools in tools/. The generic agent_* tools and the delegation service require no changes. No fake Codex/Claude adapters are shipped.

Limitations

• The OpenCode session registry is in-memory; a gateway restart forgets which directories sessions came from (OpenCode itself persists sessions by ID).

• Direct-mode workspaces (ws_...) also expire on gateway restart; reopen them with workspace_open.

• file_apply_patch requires exact context matches; no fuzzy application.

• OpenCode API is consumed as a superset of the v1 OpenAPI paths; future backend versions should be re-verified against their own /doc.

• The always permission reply is supported at the protocol level; operators may want to disable it globally to enforce per-run approvals.