agents-mcp-gateway

Secure localhost MCP gateway for Windows-native local agent work.

Only one MCP server is exposed externally: agents-mcp-gateway at http://127.0.0.1:3333/mcp. Codex and Claude are no longer used as child MCP servers. Agent work runs through ordinary non-interactive CLI subprocesses with fixed argv from local config.

Architecture

ChatGPT
  -> OpenAI Secure MCP Tunnel
  -> http://127.0.0.1:3333/mcp
      -> native bounded file/Git/search/check tools
      -> codex CLI subprocess adapter
      -> claude CLI subprocess adapter

Configuration

config/projects.yaml has two registries:

projects:
  agents-mcp-gateway:
    description: Gateway source tree
    path: D:\Projects\agents-mcp-gateway

agents:
  codex-readonly:
    description: Codex CLI non-interactive read-only agent
    adapter: codex
    args: ["exec", "--json", "-s", "read-only", "-c", "approval_policy='never'"]

  claude-readonly:
    description: Claude Code non-interactive JSON agent
    adapter: claude
    args: ["-p", "--output-format", "json", "--permission-mode", "dontAsk"]

Remote MCP callers cannot pass command, args, env, model, cwd, or arbitrary filesystem paths for an agent. They can only choose a configured agent, provide a configured project_id, and send a prompt.

Public Agent Tools

list_projects()
list_agents()
create_task(project_id, agent, prompt) -> task_id, thread_id
resume_thread(thread_id, prompt) -> task_id
get_task(task_id)
await_task(task_id, timeout_ms?) — wait up to 60 seconds for a terminal task state, defaulting to 30 seconds; if the timeout elapses, returns the latest task with wait_timed_out: true
cancel_task(task_id)
list_tasks(status?, limit?)
get_thread(thread_id)
list_threads(status?, limit?)
close_thread(thread_id)

A task is one CLI subprocess execution. A thread stores the gateway thread ID, provider session ID, adapter, agent, and canonical cwd so later tasks can resume the provider conversation without accepting project_id or agent again.

Native Tools

Native file/Git/search tools remain project-scoped:

list_files(project_id, relative_path, depth)
read_file(project_id, relative_path, start_line, end_line)
search_code(project_id, query, glob, max_results)
git_status(project_id)
git_diff(project_id, base, max_chars)
git_log(project_id, limit)
run_check(project_id, check_id)

run_check does not accept arbitrary commands. It only runs detected package scripts named test, lint, typecheck/check, or build.

CLI Probe Findings

Codex 0.146.0-alpha.3.1:

new session: codex exec --json -C <cwd> ... <prompt>
JSONL event thread.started.thread_id is the provider session ID
resume: codex exec resume --json <thread_id> <prompt>
resume command must run with process cwd set to the original cwd; resume has no -C
fixture probe confirmed new session, remembered context, and cwd continuity

Claude Code 2.1.220:

new session: claude -p --output-format json ... with prompt on stdin
JSON result has session_id
resume help exposes --resume <session_id>
current provider probe returned a quota 429, so command shape and session_id parsing are implemented, while semantic resume could not be completed in this run

Run

cd D:\Projects\agents-mcp-gateway
pnpm install
pnpm build
pnpm start

Doctor:

pnpm doctor

Tests:

pnpm test

Automatic Start

powershell -ExecutionPolicy Bypass -File scripts\install-task-scheduler.ps1

Remove:

powershell -ExecutionPolicy Bypass -File scripts\uninstall-task-scheduler.ps1

Security Notes

Server binds only to 127.0.0.1.
No router port forwarding, 0.0.0.0, or public tunnel URL is used.
External access should go through OpenAI Secure MCP Tunnel only.
Agent argv is fixed in local config.
Environment is allowlisted.
Sensitive files, credential folders, .git, node_modules, browser session stores, symlink/junction escapes, UNC paths, URL paths, and project traversal are blocked.

agents-mcp-gateway