external-agent-mcp

Local stdio MCP runtime that lets Codex delegate work to installed external CLI coding agents. Codex starts asynchronous jobs through one MCP call, then polls for status, free-form results, logs, and sandbox patch artifacts.

The server is dependency-free Node.js and speaks MCP over line-delimited JSON-RPC on stdio.

Providers

Initial provider adapters:

• Cursor Agent via CURSOR_AGENT_BIN

• Gemini CLI via GEMINI_BIN

• Claude Code via CLAUDE_BIN

Model selection is caller-controlled with the model argument. The MCP server does not hardcode routing logic such as "simple task uses X, complex task uses Y".

Related MCP server: Cursor Agent MCP Server

Tools

delegate_tasks

Creates one or more async jobs.

Required arguments:

• repo_path: absolute repository/workspace path

• provider: cursor, gemini, or claude

• tasks: array of task strings or task objects

Common optional arguments:

• mode: analysis or sandbox_patch; defaults to analysis

• model: provider-specific model override

• files: focus files under repo_path

• extra_context: additional background

• timeout_sec: defaults to 600, capped at 1800

• max_output_chars: defaults to 30000, capped at 100000

• base_ref: git ref for sandbox_patch; defaults to HEAD

Task objects may override provider, model, mode, files, extra_context, timeout_sec, max_output_chars, and base_ref.

job_status

Returns job lifecycle state and stdout/stderr tails. Status values are:

• queued

• running

• succeeded

• failed

• timed_out

• cancelled

• orphaned

If no job_id or job_ids are supplied, recent jobs are returned.

job_result

Returns the external agent's free-form result text plus MCP-managed metadata:

• command metadata and exit status

• stdout/stderr log paths

• result.md

• diff.patch, diff.stat, and changed files for sandbox_patch

search_jobs

Searches historical jobs by lightweight metadata and previews. This is the stable history lookup interface; full text and patch artifacts should still be read with job_result.

Supported filters:

• repo_path: exact repository path

• provider: cursor, gemini, or claude

• model: exact model string

• mode: analysis or sandbox_patch

• status: any of queued, running, succeeded, failed, timed_out, cancelled, or orphaned

• created_after / created_before: ISO timestamps

• query: case-insensitive substring search over title, task, result preview, paths, provider/model/mode, and focused files

• limit: defaults to 20, capped at 100

• cursor: opaque pagination cursor from a previous response

The response returns job summaries, previews, hashes, and artifact paths. It does not return large stdout, stderr, result, or patch bodies.

cancel_jobs

Cancels queued or running jobs.

cleanup_jobs

Removes terminal job logs/artifacts and associated sandbox worktrees. Use force: true only when cleaning non-terminal jobs intentionally.

agent_status

Checks provider binaries and reports capability metadata:

• supports_analysis

• supports_sandbox_patch

• supports_models

• safe_write_mode

quality_fix

Runs allow-listed deterministic quality commands over a bounded file set. This path is for mechanical fixes and does not spend LLM agent tokens.

Default commands:

• ruff_format: ruff format <files>

• ruff_safe_fix: ruff check --fix <files>

Additional commands:

• ruff_check: ruff check <files>

• ruff_unsafe_fix: ruff check --fix --unsafe-fixes <files>; requires allow_unsafe_fixes: true

Job Storage

Jobs are persisted under:

~/.cache/external-agent-mcp/jobs

Override with:

EXTERNAL_AGENT_JOB_ROOT=/path/to/jobs

Each job directory contains:

• job.json

• events.jsonl

• stdout.log

• stderr.log

• result.md

• diff.patch

• diff.stat

If the MCP server restarts, non-terminal jobs from the previous process are marked orphaned. Completed job artifacts remain readable.

The current storage implementation is FileJobStore: metadata is read from job.json, events are appended to events.jsonl, and large artifacts remain as plain files. search_jobs is intentionally defined above this storage layer so a future SQLite-backed index can replace the file scan without changing the MCP tool contract.

New jobs include stable metadata for history and future caching:

• schema_version

• repo_head

• task_hash

• prompt_hash

• duration_ms

• result_preview

Sandbox Patch Mode

mode: "sandbox_patch" requires a git repository. The server creates an isolated git worktree under the job directory, runs the external agent there, and then captures git diff --binary and git diff --stat.

The original repository is not modified by agent writes.

Provider write policy is conservative:

• Cursor sandbox patch is marked experimental and is launched without --force or --yolo.

• Gemini uses --approval-mode auto_edit.

• Claude uses --permission-mode acceptEdits with a restricted tool list.

• The server rejects adapter commands that include --force, --yolo, or bypass-permission flags.

Codex Config

Add this to ~/.codex/config.toml or a trusted project .codex/config.toml:

[mcp_servers.external_agent]
command = "node"
args = ["/path/to/external-agent-mcp/src/server.mjs"]
startup_timeout_sec = 10
tool_timeout_sec = 900

[mcp_servers.external_agent.env]
CURSOR_AGENT_BIN = "/path/to/cursor"
GEMINI_BIN = "/path/to/gemini"
CLAUDE_BIN = "/path/to/claude"
RUFF_BIN = "ruff"
EXTERNAL_AGENT_ALLOWED_ROOTS = "/path/to/workspace:/path/to/another-workspace"
EXTERNAL_AGENT_MAX_CONCURRENCY = "2"

After changing MCP config, refresh/restart Codex or start a new thread so the new tool surface is loaded.

Examples

Parallel Analysis

{
  "provider": "cursor",
  "model": "your-model-name",
  "repo_path": "/path/to/your-repo",
  "mode": "analysis",
  "tasks": [
    "Map the request lifecycle from the API handler to the service layer. Return concise findings with file paths.",
    "Audit authentication and permission boundaries. Return risks and missing tests."
  ],
  "timeout_sec": 900
}

Sandbox Patch

{
  "provider": "claude",
  "repo_path": "/path/to/your-repo",
  "mode": "sandbox_patch",
  "tasks": [
    {
      "task": "Fix the focused Ruff SIM102 issue and summarize the patch.",
      "files": ["src/example/path.py"]
    }
  ]
}

Then call job_status until terminal and job_result to inspect the free-form result, logs, and patch path.

Search History

{
  "repo_path": "/path/to/your-repo",
  "provider": "cursor",
  "model": "your-model-name",
  "mode": "analysis",
  "status": ["succeeded", "failed"],
  "query": "request lifecycle",
  "limit": 20
}

Deterministic Ruff Fix

{
  "repo_path": "/path/to/your-repo",
  "files": ["src/example/path.py"],
  "commands": ["ruff_format", "ruff_safe_fix"],
  "timeout_sec": 120,
  "max_changed_files": 10
}

Manual Test

npm test