external-agent-mcp
The external-agent-mcp server provides an MCP interface to delegate coding tasks to external CLI agents (Cursor, Gemini, Claude), manage asynchronous jobs, and run deterministic quality fixes.
Delegate Tasks: Create one or more async jobs targeting external CLI agents. Supports parallel execution (up to 50 tasks), two modes (
analysisfor read-only inspection,sandbox_patchfor isolated code changes in git worktrees), model selection, file focusing, custom context, and per-task overrides.Monitor Job Status: Poll lifecycle states (
queued,running,succeeded,failed,timed_out,cancelled,orphaned) and view stdout/stderr tails. Lists recent jobs if no specific job ID is provided.Retrieve Job Results: Fetch full result text, command metadata, exit status, log paths, and for sandbox patches:
result.md,diff.patch,diff.stat, and changed file lists.Search Job History: Query past jobs by repo path, provider, model, mode, status, date range, or free-text substring, with pagination support.
Cancel Jobs: Stop any queued or running jobs by ID.
Clean Up Jobs: Remove logs, artifacts, and sandbox worktrees for terminal jobs; use
force: truefor non-terminal jobs.Check Agent Status: Verify provider CLI binaries are installed and report capability metadata (e.g.,
supports_analysis,supports_sandbox_patch,safe_write_mode).Run Quality Fixes: Execute allow-listed Ruff commands (
ruff_format,ruff_safe_fix,ruff_check,ruff_unsafe_fix) over a bounded file set without spending LLM tokens, with diff stats and unsafe fix opt-in.
Provides tools to run Ruff formatter and linter for automated code formatting and safe fixes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@external-agent-mcp analyze code with gemini for performance issues"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_BINGemini CLI via
GEMINI_BINClaude 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: Codex to OpenCode MCP Server
Tools
delegate_tasks
Creates one or more async jobs.
Required arguments:
repo_path: absolute repository/workspace pathprovider:cursor,gemini, orclaudetasks: array of task strings or task objects
Common optional arguments:
mode:analysisorsandbox_patch; defaults toanalysismodel: provider-specific model overridefiles: focus files underrepo_pathextra_context: additional backgroundtimeout_sec: defaults to600, capped at1800max_output_chars: defaults to30000, capped at100000base_ref: git ref forsandbox_patch; defaults toHEAD
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:
queuedrunningsucceededfailedtimed_outcancelledorphaned
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.mddiff.patch,diff.stat, and changed files forsandbox_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 pathprovider:cursor,gemini, orclaudemodel: exact model stringmode:analysisorsandbox_patchstatus: any ofqueued,running,succeeded,failed,timed_out,cancelled, ororphanedcreated_after/created_before: ISO timestampsquery: case-insensitive substring search over title, task, result preview, paths, provider/model/mode, and focused fileslimit: defaults to20, capped at100cursor: 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_analysissupports_sandbox_patchsupports_modelssafe_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>; requiresallow_unsafe_fixes: true
Job Storage
Jobs are persisted under:
~/.cache/external-agent-mcp/jobsOverride with:
EXTERNAL_AGENT_JOB_ROOT=/path/to/jobsEach job directory contains:
job.jsonevents.jsonlstdout.logstderr.logresult.mddiff.patchdiff.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_versionrepo_headtask_hashprompt_hashduration_msresult_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
--forceor--yolo.Gemini uses
--approval-mode auto_edit.Claude uses
--permission-mode acceptEditswith 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 testAvailable Tools
9 toolsagent_statusA
Check configured external CLI agent binaries and report provider capability metadata.
Inputs: provider, timeout_sec.
analyze_codeA
Deprecated compatibility wrapper around delegate_tasks for one read-only analysis job. Prefer delegate_tasks + job_result.
Inputs: task (required), provider (required), repo_path (required), files, +5 more.
cancel_jobsC
Cancel queued or running asynchronous jobs.
Inputs: job_ids (required).
cleanup_jobsA
Remove terminal job logs/artifacts and associated sandbox worktrees. Non-terminal jobs require force=true.
Inputs: job_ids (required), force.
delegate_tasksA
Create one or more asynchronous external-agent jobs. Use job_status and job_result to inspect completion and artifacts.
Inputs: tasks (required), provider (required), repo_path (required), mode, +6 more.
job_resultB
Read completed or in-progress job outputs, free-form result text, diff metadata, and artifact paths.
Inputs: job_id, job_ids, include_stderr, max_output_chars.
job_statusA
Read asynchronous job status, including stdout/stderr tails. If no job_ids are supplied, returns recent jobs.
Inputs: limit, job_id, job_ids, tail_chars.
quality_fixB
Run deterministic allow-listed quality commands such as Ruff format and safe fixes over a bounded file set.
Inputs: repo_path (required), files, commands, timeout_sec, +5 more.
search_jobsA
Search historical external-agent jobs by metadata and lightweight previews. Use job_result for full artifacts.
Inputs: mode, limit, model, query, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools are clearly distinct, focusing on different aspects of job lifecycle (delegate, status, result, cancel, cleanup) and configuration. The deprecated analyze_code tool overlaps with delegate_tasks, creating minor ambiguity, but it's clearly marked deprecated.
All tool names follow a consistent snake_case verb_noun pattern (e.g., cancel_jobs, cleanup_jobs, delegate_tasks, job_status, quality_fix). There are no mixed conventions, making the set predictable for an agent.
With 9 tools, the server is well-scoped for its purpose of managing external agent jobs. Each tool serves a necessary function without superfluous additions, and the count balances coverage and simplicity.
The tool surface covers the main job lifecycle (create, status, result, cancel, cleanup) plus search, configuration check, and a specific quality fix. Minor gap: a dedicated list_jobs tool is missing, but job_status with no job_ids returns recent jobs, covering that need.
Maintenance
Related MCP Connectors
Run verified read-only code tools: quant diagnostics + agent-ops preflight, no source exposure.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Lets coding agents check their own code for leaked secrets, risky dependencies and AI-code mistakes
Research-backed lint + generation for agent context files (CLAUDE.md, AGENTS.md) + prompt enhancer.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP bridge for calling local coding-agent CLIs (Codex, Claude) from another agent, enabling bounded tasks like code review, verification, and bug hunting.MIT
- AlicenseAqualityDmaintenanceEnables Codex to delegate coding tasks to an OpenCode CLI locally, returning structured results such as exit codes, session summaries, tool calls, and git diffs.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude Code to delegate bounded, read-only analysis and isolated patch proposals to the locally installed Codex CLI over MCP, with sanitized live status, revision-aware polling, and reviewable results.1MIT
- AlicenseAqualityCmaintenanceEnables MCP-compatible coding agents to execute the local Codex CLI as a coding agent, including code reviews, session resume/fork, and CLI diagnostics.9MIT