# 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

```text
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:

```yaml
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

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

Doctor:

```powershell
pnpm doctor
```

Tests:

```powershell
pnpm test
```

## Automatic Start

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

Remove:

```powershell
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.