@sealgate/agent-cli-mcp

A thin stdio MCP server that runs a local coding-agent CLI headlessly and exposes it as a single run tool. It ships two flavors, selected by argument:

| Argument | Wraps | Headless command | | ---------- | ---------------- | ---------------- | | codex | OpenAI Codex CLI | codex exec | | opencode | OpenCode CLI | opencode run |

It is designed to be launched on a user's own machine by the SealGate daemon over a stdio tunnel, so the coding agent runs locally (with the user's own CLI auth and config) while every tool call is mediated by the SealGate data firewall.

Usage

The wrapped CLI (codex or opencode) must already be installed and authenticated on PATH on the machine that runs this server. This package does not install or configure the CLI.

# Wrap the Codex CLI:
npx -y @sealgate/agent-cli-mcp codex

# Wrap the OpenCode CLI:
npx -y @sealgate/agent-cli-mcp opencode

# Pin a default working dir / model / reasoning effort at launch (codex shown):
npx -y @sealgate/agent-cli-mcp codex --cwd /path/to/project --model gpt-5-codex --effort high

The server speaks MCP over stdio and exposes one tool:

run

Run a single headless coding task.

| Field | Type | Required | Description | | -------- | ------ | -------- | --------------------------------------------------------------------------------------------------- | | prompt | string | yes | The task or question for the coding agent. | | cwd | string | no | Absolute path to the working directory. Blank or unusable is treated as omitted. See "Working directory" below. | | model | string | no | Override the model (passed through to the CLI as-is). | | effort | enum | no | minimal|low|medium|high reasoning effort. Codex only. |

cwd, model and effort can also be pinned server-wide at launch, so a marketplace entry sets them once instead of every caller passing them: pass --cwd <dir> / --model <m> / --effort <e> after the agent selector, or set AGENT_CLI_MCP_CWD / AGENT_CLI_MCP_MODEL / AGENT_CLI_MCP_EFFORT. A per-call run argument overrides the server default; a launch flag overrides the env var. effort is ignored for OpenCode.

Model precedence: per-call model > launch default (--model / AGENT_CLI_MCP_MODEL) > the agent's built-in fallback. Codex has no built-in fallback (it reads ~/.codex/config.toml); OpenCode's is defaultModel in src/agents.ts (a chat + tool-calling model), because its own unconfigured auto-pick can select a non-chat model. Override it with any of the above.

Working directory

You never have to pass cwd. A blank or whitespace-only value counts as not given (some clients send "" for an unset field). It is resolved in this order:

1. the per-call cwd argument, if given (and non-blank);
2. the launch default (--cwd / AGENT_CLI_MCP_CWD), if set;
3. otherwise a single temp workspace created on first use and reused for the life of this server, so successive run calls share files and state instead of each getting a throwaway directory.

A cwd that does not exist (or is not a directory) does not fail the run, at either the per-call or the launch-default level. The bad path is skipped with a warning on stderr and resolution falls through to the next option above (ultimately the session workspace), so a hallucinated or typo'd path still lets the agent work rather than erroring out.

Progress logs are streamed by the CLI to stderr; the tool returns the CLI's final output. On a non-zero exit or timeout, isError is set and stdout/stderr are included for debugging.

Progress (step-level)

While a run is in flight the server emits MCP notifications/progress (when the caller supplies a progressToken) so the call does not look hung, and so clients that reset their request timeout on progress stay alive through long reasoning (see the timeout note below).

Both wrapped CLIs are run in a structured event mode (codex exec --json, opencode run --format json), whose JSONL event streams the server parses into real step labels rather than a raw log line. So progress reads like Running: python3 fib.py, Ran: python3 fib.py (exit 0), Edited: add fib.py, Thinking…, Response ready, emitted as each step happens. The agent's final answer is reassembled from the stream's agent_message / text events and returned as the tool result (the raw JSONL is never surfaced).

Note there is no meaningful percentage: agent loops are open-ended, so the progress field is a monotonic counter with no total. Set AGENT_CLI_MCP_STRUCTURED=0 to disable structured mode and fall back to raw stdout with the latest stderr line as the progress message.

Activity summary in the result

Progress notifications keep a call alive, but many MCP clients do not feed each one into the calling model's context, so a run that wrote files and ran commands can come back as a bare final line. To give the caller a high-level picture of what the agent actually did, the server appends a compact Activity summary to the tool result (after the final answer), reconstructed from the same event stream:

Created fib.py and ran it with python3. Result: fib(10) = 55

--- Activity (3 steps) ---
- Plan: 1. Create fib.py with a fib(n) function. 2. Run it. 3. Report the result.
- edited add fib.py
- ran `/bin/bash -lc 'python3 fib.py'` -> exit 0 | 55

It records commands (with exit code and a snippet of output), file edits (with path and add/modify/delete), searches, model reasoning (including reasoning that OpenCode nests inside a tool call), and any intermediate assistant messages (e.g. an up-front plan), in the order they happened. Intermediate messages are folded into the summary so the final answer above stays clean. The summary is on by default (opt-out): set AGENT_CLI_MCP_TRACE=0 to omit it and return only the answer.

Timeouts

There are two independent clocks, and they are usually confused:

1. The MCP client's request timeout. The client that calls run decides how long to wait for a response. A headless coding agent can reason for minutes while emitting only stderr, so a client with a short request timeout aborts a perfectly healthy run. This server mitigates that by sending progress heartbeats (above); a client should enable its "reset timeout on progress" behavior (and a generous max total timeout) to benefit. This is the clock that usually fires. Raising AGENT_CLI_MCP_TIMEOUT_MS does not affect it.
2. This server's subprocess cap (AGENT_CLI_MCP_TIMEOUT_MS). A hard ceiling on how long the wrapped CLI may run before it is killed. It is the backstop for a genuinely stuck CLI, not the knob for "the client timed out".

Environment

| Variable | Default | Description | | ---------------------------- | --------- | -------------------------------------------------------------- | | AGENT_CLI_MCP_TIMEOUT_MS | 1800000 | Per-run subprocess timeout in milliseconds (hard cap). | | AGENT_CLI_MCP_HEARTBEAT_MS | 10000 | Interval between progress heartbeats while a run is live. | | AGENT_CLI_MCP_MODEL | (unset) | Server-wide default model; a launch flag or per-call arg wins. | | AGENT_CLI_MCP_EFFORT | (unset) | Server-wide default reasoning effort (codex). | | AGENT_CLI_MCP_CWD | (unset) | Server-wide default working directory. | | AGENT_CLI_MCP_STRUCTURED | 1 | Structured step-level progress via the CLI's JSONL events; 0 disables. | | AGENT_CLI_MCP_TRACE | 1 | Append an Activity summary of what the agent did to the result; 0 omits it. |

Security notes

• Arguments are passed as argv with shell: false, so no shell is spawned and the prompt cannot inject shell commands into the launcher.
• The coding agent itself can read and modify files in cwd and run commands, subject to its own sandbox/approval configuration. In the marketplace catalog the run tool is classified SECRET (write + private-read + untrusted-read) so the SealGate firewall treats it as maximally sensitive.

Development

npm install
npm run build       # tsc -> dist/
npm run typecheck

Publishing is automated: pushing a tag agent-cli-mcp-v<version> triggers .github/workflows/publish-agent-cli-mcp.yaml, which builds and publishes to npm (requires the NPM_TOKEN repository secret). See that workflow for the first-run setup.