The agent-bridge-mcp server lets you delegate tasks to local AI coding CLIs (Claude, Codex, Forge, OpenCode, Antigravity) running as background jobs, managed through MCP tools:
Start a background agent job (run): Launch a CLI process with a prompt or prompt file, optionally specifying model, reasoning effort, working directory, or session ID; returns a PID immediately without blocking.
List tracked processes (list_processes): View all process IDs, agent types, and statuses (running, completed, failed).
Inspect results (get_result): Fetch current output and status for a given PID, with optional verbose metadata (start time, work folder, prompt, parsed output).
Wait for completion (wait): Monitor one or more PIDs until they finish or a timeout is reached.
Observe live output (peek): Watch a short live window of natural-language messages and optional tool-call events from running agents.
Terminate a process (kill_process): Send SIGTERM to a running process by PID.
Clean up finished records (cleanup_processes): Remove completed/failed process entries from memory and the persistent registry (log files are preserved).
Check CLI availability (doctor): Verify that supported CLI binaries are installed and resolvable.
Browse supported models (models): List model names, aliases, and dynamic model syntax for OpenCode.
Additional features include: session resume across supported agents, reasoning effort control for Claude and Codex, a persistent registry under ~/.agent-bridge-mcp that survives server restarts, and custom CLI binary path configuration via environment variables.
The underlying agents can perform file operations, code generation/refactoring, git workflows, terminal commands, web search, and multi-step automation.
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., "@agent-bridge-mcp run codex to refactor auth module in /projects/app"
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.
MCP-only server for running local Claude, Codex, Forge, OpenCode, and Antigravity CLI agents as background jobs.
English | 简体中文
agent-bridge-mcp lets an MCP client delegate work to AI coding CLIs already installed on your machine. It does not call model APIs directly. Instead, it starts local Claude, Codex, Forge, OpenCode, or Antigravity CLI processes in the background, returns a PID immediately, and exposes MCP tools to inspect, wait for, peek at, terminate, and clean up those jobs.
The package has one executable entry point:
agent-bridge-mcpMost AI CLIs are excellent at real local work: editing files, running commands, searching code, using project context, and continuing long tasks. MCP clients, however, need a stable tool contract and should not block while a long agent process runs.
This server bridges that gap:
Start long-running local AI CLI tasks through MCP.
Return immediately with a PID instead of waiting for completion.
Query compact or verbose results later.
Observe short windows of live natural-language output with peek.
Use one MCP contract across Claude, Codex, Forge, OpenCode, and Antigravity.
Keep live process handles in memory and persist lightweight process metadata/log paths for recovery across MCP server restarts.
Related MCP server: MCP Background Task Server
agent-bridge-mcp is intentionally narrow:
It is not a model API gateway.
It is not a human-facing terminal CLI suite.
It does not provide ai-cli run, ai-cli ps, or similar subcommands.
It persists process metadata and stdout/stderr logs under ~/.agent-bridge-mcp by default; set AGENT_BRIDGE_PROCESS_REGISTRY_DIR to override the location.
It does not verify CLI login state, subscriptions, model access, or terms acceptance.
The server can launch these local tools:
Claude CLI
Codex CLI
Forge CLI
OpenCode CLI
Antigravity CLI
You must install, configure, and sign in to the CLIs you plan to use before calling run. doctor only checks whether binaries can be resolved and executed; it does not check account state.
Gemini CLI support has been removed because that CLI is no longer maintained. Legacy gemini-* models and gemini-ultra are rejected instead of being routed to another agent.
Node.js ^20.19.0 || >=22.12.0
npm
At least one supported AI CLI installed locally
An MCP client that supports stdio servers
git clone https://github.com/lailai258/agent-bridge-mcp.git
cd agent-bridge-mcp
npm install
npm run buildStart the built MCP server:
npm startDevelopment mode:
npm run devIf installed from npm, the package name is:
npm install -g agent-bridge-mcp-serverThen start the stdio server with:
agent-bridge-mcpUse the package executable when it is available on PATH:
{
"mcpServers": {
"agent-bridge-mcp": {
"command": "agent-bridge-mcp",
"args": []
}
}
}Or point your MCP client at the built server file:
{
"mcpServers": {
"agent-bridge-mcp": {
"command": "node",
"args": [
"/absolute/path/to/agent-bridge-mcp/dist/server.js"
]
}
}
}MCP registry metadata is available in server.json.
Call run from your MCP client:
{
"model": "codex-ultra",
"workFolder": "/absolute/path/to/project",
"prompt": "Review this repository and identify the most important test failures."
}The server returns immediately:
{
"pid": 12345,
"status": "started",
"agent": "codex",
"message": "codex process started successfully"
}Later, inspect the process:
{
"pid": 12345,
"verbose": true
}Or wait for it:
{
"pids": [12345],
"timeout": 300,
"on_timeout": "return_status",
"verbose": false
}All tool responses are returned as MCP text content containing pretty-printed JSON.
runStarts a new local AI CLI child process in the background and returns a PID immediately.
Required:
workFolder: absolute working directory for the agent process.
Prompt input, exactly one required:
prompt: inline task prompt.
prompt_file: absolute path or path relative to workFolder.
Optional:
model: standard model, alias, or OpenCode dynamic model. Use antigravity to select Antigravity CLI.
reasoning_effort: supported only for Claude and Codex.
session_id: resume an existing CLI session where the selected CLI supports it.
list_processesLists tracked processes from current server memory plus the persisted process registry:
pid
agent
status
Statuses are running, completed, or failed.
get_resultReturns the current status and output for one PID.
Parameters:
pid: PID returned by run.
verbose: include metadata such as startTime, workFolder, prompt, and fuller parsed output.
waitWaits for one or more tracked processes to finish.
Parameters:
pids: non-empty PID array.
timeout: logical wait budget in seconds. Defaults to 900 and can be raised with AGENT_BRIDGE_WAIT_TIMEOUT_SEC.
on_timeout: return_status by default; returns current running results when the per-call observation window expires. Use throw only for legacy timeout errors.
verbose: return verbose result objects.
One MCP tool call observes at most AGENT_BRIDGE_WAIT_CALL_WINDOW_SEC seconds, default 90 and capped at 110, so host tools/call deadlines are not hit while long-running child processes keep running.
peekObserves a short live output window for running processes.
Parameters:
pids: PID array. Duplicates are removed while preserving first-seen order.
peek_time_sec: positive integer, default 10, maximum 60.
include_tool_calls: include normalized tool-call events without raw tool output.
Important boundaries:
peek is not a history API.
peek is not a gapless stream.
peek is not stdout/stderr tailing.
Tool calls are summarized; raw tool output is excluded.
kill_processSends SIGTERM to a running process by PID.
cleanup_processesRemoves completed and failed process records from the server's in-memory process table and persisted registry. Log files are left on disk for troubleshooting.
doctorReports binary path resolution for supported CLIs:
configured command
resolved path
availability
lookup source
configuration errors
It does not verify login state, terms acceptance, model permissions, or network connectivity.
modelsLists supported model names, aliases, Antigravity entrypoint, and OpenCode dynamic model syntax.
claude-ultra -> Claude opus, with default reasoning_effort=max
codex-ultra -> Codex gpt-5.5, with default reasoning_effort=xhigh
Claude:
sonnet
sonnet[1m]
deepseek-v4-pro[1m]
deepseek-v4-flash[1m]
glm-5.1
opus
opusplan
haiku
Codex:
gpt-5.4
gpt-5.5
gpt-5.4-mini
gpt-5.3-codex
gpt-5.3-codex-spark
gpt-5.2
Forge:
forge
OpenCode:
opencode
oc-<provider/model>
Antigravity:
antigravity
antigravity selects the Antigravity CLI agent. This integration does not pass a model flag to agy.
Example dynamic OpenCode model:
{
"model": "oc-openai/gpt-5.4",
"workFolder": "/absolute/path/to/project",
"prompt": "Find the highest-risk regression in this branch."
}Example OpenCode DeepSeek v4 Pro model:
{
"model": "oc-opencode-go/deepseek-v4-pro",
"workFolder": "/absolute/path/to/project",
"prompt": "Find the highest-risk regression in this branch."
}reasoning_effort is intentionally limited by agent family:
Claude: low, medium, high, xhigh, max
Codex: low, medium, high, xhigh
Forge: not supported
OpenCode: not supported
Antigravity: not supported
Invalid combinations are rejected before launching the child process.
The optional session_id parameter is passed to the selected CLI using that CLI's native resume mechanism:
Claude: resume with forked session behavior.
Codex: exec resume <session_id>.
Forge: conversation ID.
OpenCode: --session.
Antigravity: --conversation <session_id> in print mode.
Session behavior still depends on the installed CLI version and its own storage model.
By default, the server resolves CLIs from common local install paths and PATH.
Override a CLI command or absolute path with environment variables:
CLAUDE_CLI_NAME
CODEX_CLI_NAME
FORGE_CLI_NAME
OPENCODE_CLI_NAME
ANTIGRAVITY_CLI_NAME
Values may be simple command names or absolute paths. Relative paths such as ./claude or tools/codex are rejected.
Enable debug logging with:
MCP_CLAUDE_DEBUG=true agent-bridge-mcpMCP Client
↓ stdio / tools.call
MCP Server Boundary src/app/mcp.ts
↓
Runtime Process Layer src/process-service.ts
↓
CLI Adapter Layer src/cli-builder.ts / src/cli-utils.ts
↓
Local AI CLI Processes claude / codex / forge / opencode / agyCore modules:
src/app/mcp.ts: MCP server, tool registration, handler dispatch, error mapping.
src/process-service.ts: process lifecycle management, wait/peek/kill orchestration, and registry integration.
src/process-registry.ts: persisted process metadata and stdout/stderr log paths.
src/cli-builder.ts: converts run input into safe CLI argument arrays.
src/cli-utils.ts: CLI path resolution and doctor status.
src/model-catalog.ts: model lists, aliases, Antigravity entrypoint, and OpenCode dynamic model metadata.
src/parsers.ts: output parsers and peek event extraction.
src/process-result.ts: compact and verbose result shaping.
src/peek.ts: peek validation and response helpers.
Live child process handles exist only in the current Node.js server process. Lightweight process metadata and stdout/stderr log paths are persisted in the local registry, which defaults to ~/.agent-bridge-mcp and can be changed with AGENT_BRIDGE_PROCESS_REGISTRY_DIR.
Consequences:
A PID returned by run can be observed live while the same MCP server process is alive.
Restarting the MCP server cannot reattach to live stdout/stderr streams, but it can recover basic results and log-backed output for recorded PIDs.
cleanup_processes removes finished records from memory and the persisted registry; it does not delete log files.
Each run call starts a new child process.
Important: some CLI adapters intentionally launch local agents with approval or sandbox bypass flags so that background jobs can complete without interactive prompts. Claude and Antigravity use --dangerously-skip-permissions; Codex uses --dangerously-bypass-approvals-and-sandbox. Only run this server against work folders you trust, and review the selected CLI's own security model before exposing it to untrusted prompts or repositories.
Child processes are spawned with argument arrays rather than shell-concatenated prompt strings.
Custom CLI environment variables reject relative paths.
peek excludes raw tool output and raw command output.
Verbose results include the prompt, so avoid sending secrets in prompts.
External CLI sandboxing, network access, file permissions, and approval behavior are controlled by the selected CLI, not by this server.
Install dependencies:
npm installBuild:
npm run buildRun unit tests:
npm run test:unitRun the full test suite:
npm testCheck package contents before publishing:
npm_config_cache="/private/tmp/agent-bridge-mcp-npm-cache" npm pack --dry-runAdditional project documentation:
MIT. See LICENSE.
Remove all completed and failed processes from the process list to free up memory.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It clearly states the action (removing completed/failed processes) and the benefit (free memory). It does not mention edge cases like empty list or return value, but for a simple zero-parameter tool, it is sufficiently transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence front-loads the purpose and outcome. No wasted words, highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema, no annotations), the description is adequate. It covers what it does and why. Could mention that it does not affect running processes, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so baseline is 4. The description adds no parameter info because none exist. Schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool removes all completed and failed processes to free memory. It uses specific verbs and resource, and distinguishes from siblings like kill_process (which targets running processes) and list_processes (which lists them).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for memory cleanup but does not explicitly tell when to use this tool versus alternatives (e.g., kill_process for running processes). No guidance on prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check supported AI CLI binary availability and path resolution. Does not verify login state or terms acceptance.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It transparently states its scope (binary availability and path resolution) and limitations (does not verify login state or terms acceptance). This is sufficient for a simple diagnostic tool with no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. First sentence states the main action, second sentence clarifies limits. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no params, no output schema), the description is fairly complete. It covers purpose and limitations. However, it does not describe the return value or format, which could be useful for the agent to interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (empty). The description adds no parameter information, but none is needed. Baseline 4 is appropriate as the description does not need to compensate for missing param details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: checking AI CLI binary availability and path resolution. It also explicitly states what it does not do (verify login state or terms acceptance), which distinguishes it from sibling tools like 'run' or 'models'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage before running commands to verify CLI availability. It provides context by clarifying what it does not check, helping the agent know when to use this tool versus others. However, it does not explicitly mention when not to use it or name alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current output and status of an AI agent process by PID. Defaults to a compact result shape; set verbose to true for full metadata and detailed parsed output.
| Name | Required | Description | Default |
|---|---|---|---|
| pid | Yes | The process ID returned by run tool. | |
| verbose | No | Optional: If true, returns the full result shape including metadata fields and detailed parsed output such as tool usage history. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description accurately states it retrieves data, implying a read-only operation. However, it lacks explicit details on side effects, resource usage, or error conditions, which would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two sentences to convey all necessary information without any redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality and result shapes adequately. While it could hint at the output structure, the tool's simplicity and the presence of sibling tools make this sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds value by explaining the behavior of the verbose parameter, going beyond the schema's static definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves output and status of an AI agent process by PID, specifying the action and resource. It effectively distinguishes itself from sibling tools like kill_process or run.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on the verbose parameter (compact vs. full output) but does not explicitly differentiate when to use this tool versus alternatives like peek or wait.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Terminate a running AI agent process by PID.
| Name | Required | Description | Default |
|---|---|---|---|
| pid | Yes | The process ID to terminate. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose side effects, required permissions, or what happens to process resources upon termination. For a destructive action, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, the brevity sacrifices valuable context for the tool's use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward kill command with one parameter, the description is adequate but does not cover behavioral aspects or differentiate from siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with 'pid' described. The description adds no additional meaning beyond what the schema provides, which is acceptable given the simple parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Terminate a running AI agent process by PID' with a specific verb and resource. However, it does not differentiate from sibling tool 'cleanup_processes', which may also terminate processes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'cleanup_processes'. The description lacks context for appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all running and completed AI agent processes. Returns a simple list with PID, agent type, and status for each process.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool returns a simple list with PID, agent type, and status for each process, but does not disclose behavioral traits such as performance characteristics, rate limits, or whether it blocks. Since no annotations are provided, the description carries the full burden, but it only minimally covers behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the core action, and no unnecessary words. Straightforward and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with no parameters and no output schema, the description adequately covers the return format and scope. However, it could mention that no detailed process information is provided (e.g., no resource usage) or that it is read-only, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so schema coverage is 100% by definition. The description naturally adds no parameter information, but the baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all running and completed AI agent processes, specifying the resource (processes) and action (list). It distinguishes from sibling tools like cleanup_processes, kill_process, etc., by focusing on listing rather than modifying or inspecting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., when to use 'peek' or 'get_result'). There is no mention of prerequisites, exclusions, or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List supported model names, model aliases, and dynamic backend discovery hints.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, idempotency, or required permissions. As a list operation, it is likely safe, but this is not explicitly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant information. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not specify return format or structure. For a simple list, it may be sufficient, but additional details on ordering, pagination, or static vs dynamic content would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is trivially 100%. The description adds meaning by specifying what the list contains (names, aliases, discovery hints), which is helpful beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists supported model names, aliases, and dynamic backend discovery hints. It is specific and distinct from sibling tools like list_processes or get_result.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or when not to use. The purpose is implied but no alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One-shot short observation window for running child agents. Returns only natural-language message events, and optionally normalized tool_call events, observed during this call; not a history API, not gapless streaming, and not stdout/stderr tailing. In v1, message extraction is supported for Codex, Claude, OpenCode, Gemini, and best-effort Forge Summary/Completed successfully lines. Forge tool calls are low-precision Execute/Finished markers and never include command output. Tool calls exclude raw tool output.
| Name | Required | Description | Default |
|---|---|---|---|
| pids | Yes | Process IDs returned by run. Duplicates are deduplicated server-side, preserving first occurrence order. Unknown PIDs are returned per process as not_found. | |
| peek_time_sec | No | Optional positive integer observation window in seconds. Defaults to 10; maximum is 60. | |
| include_tool_calls | No | Optional: include normalized tool_call events without raw tool output. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that the tool is a one-shot observation, returns only message events, tool calls are normalized without raw output, Forge support is limited, and message extraction supports specific agents. It does not mention side effects, rate limits, or authentication, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of three sentences that front-load the essential purpose and limitations. Every sentence adds value without repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters and no output schema or annotations, the description covers the purpose, return content (message events, optional tool calls), limitations (Forge precision), and supported agents. It is sufficient for an agent to decide when to use this tool, though it omits return structure details that an output schema would provide.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already defines parameters (pids, peek_time_sec, include_tool_calls) with clear descriptions. The tool description adds overall context but does not enhance parameter semantics beyond what the schema provides. A score of 3 is appropriate as the schema carries the primary burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a 'one-shot short observation window for running child agents' that returns 'natural-language message events' and optionally 'normalized tool_call events', distinguishing it from a history API, gapless streaming, and stdout/stderr tailing. The verb 'peek' accurately reflects a quick, limited observation, and the tool's scope is specific and well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when not to use this tool (not for history, streaming, or stdout/stderr) and notes limitations like Forge tool calls being low-precision and excluding raw output. However, it does not directly reference sibling tools or provide explicit guidance on which alternative to use for specific needs, such as 'get_result' for full output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
AI Agent Runner: Starts a Claude, Codex, Gemini, Forge, or OpenCode CLI process in the background and returns a PID immediately. Use list_processes and get_result to monitor progress.
• File ops: Create, read, (fuzzy) edit, move, copy, delete, list files, analyze/ocr images, file content analysis • Code: Generate / analyse / refactor / fix • Git: Stage ▸ commit ▸ push ▸ tag (any workflow) • Terminal: Run any CLI cmd or open URLs • Web search + summarise content on-the-fly • Multi-step workflows & GitHub integration
IMPORTANT: This tool now returns immediately with a PID. Use other tools to check status and get results.
Supported models: "claude-ultra", "codex-ultra", "gemini-ultra", "sonnet", "sonnet[1m]", "opus", "opusplan", "haiku", "gpt-5.4", "gpt-5.5", "gpt-5.4-mini", "gpt-5.3-codex", "gpt-5.3-codex-spark", "gpt-5.2", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview", "forge", "opencode", "oc-<provider/model>"
Prompt input: You must provide EITHER prompt (string) OR prompt_file (file path), but not both.
Prompt tips
Be concise, explicit & step-by-step for complex tasks.
Check process status with list_processes
Get results with get_result using the returned PID
Kill long-running processes with kill_process if needed
| Name | Required | Description | Default |
|---|---|---|---|
| prompt | No | The detailed natural language prompt for the agent to execute. Either this or prompt_file is required. | |
| prompt_file | No | Path to a file containing the prompt. Either this or prompt is required. Must be an absolute path or relative to workFolder. | |
| workFolder | Yes | The working directory for the agent execution. Must be an absolute path. | |
| model | No | The model to use. Aliases: "claude-ultra" (auto max effort), "codex-ultra" (auto xhigh reasoning), "gemini-ultra". Standard: "sonnet", "sonnet[1m]", "opus", "opusplan", "haiku", "gpt-5.4", "gpt-5.5", "gpt-5.4-mini", "gpt-5.3-codex", "gpt-5.3-codex-spark", "gpt-5.2", "gemini-2.5-pro", "gemini-2.5-flash", "gemini-3.1-pro-preview", "gemini-3-pro-preview", "gemini-3-flash-preview", "forge", "opencode". OpenCode also accepts explicit dynamic models using "oc-<provider/model>". "forge" is a provider key, not a Forge model family selector. | |
| reasoning_effort | No | Reasoning control for Claude and Codex. Claude uses --effort with "low", "medium", "high", "xhigh", "max". Codex uses model_reasoning_effort with "low", "medium", "high", "xhigh". Gemini, Forge, and OpenCode do not support reasoning_effort in this integration. | |
| session_id | No | Optional session ID to resume a previous session. Supported for Claude, Codex, Gemini, Forge, and OpenCode. OpenCode resumes in-place via --session and may also be combined with explicit oc-<provider/model> selection. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states that the tool returns immediately with a PID and lists supported models. It also implies destructiveness by including 'delete files' in capabilities but provides no warnings or details about error handling, permissions, or side effects of processes. This is adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with bullet points and sections, making it scannable. It includes necessary details but is somewhat lengthy. Some redundancy (e.g., repeated emphasis on PID workflow) could be trimmed, but overall it is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 params, no output schema, multiple sibling tools), the description covers the essential workflow, model options, and parameter constraints. However, it lacks details on error responses, return format beyond PID, and potential limitations (e.g., max prompt length, timeout behavior). This makes it adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description adds value beyond the schema by providing context for the model parameter (aliases and provider explanations), the mutual exclusivity of prompt and prompt_file, and the workflow of using the returned PID. It enhances understanding of how to use the parameters effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool starts an AI agent CLI process in the background and returns a PID immediately. It lists specific capabilities (file ops, code, git, terminal, web search) and distinguishes itself from sibling tools like list_processes, get_result, and kill_process by directing users to use those for monitoring and results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs to use list_processes and get_result for monitoring progress and includes prompt tips (e.g., 'Be concise, explicit & step-by-step for complex tasks'). It mentions that prompt and prompt_file are mutually exclusive. However, it does not explicitly state when not to use this tool versus alternatives like peek or wait, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Wait for multiple AI agent processes to complete and return their results. Defaults to compact result items; set verbose to true for full metadata and detailed parsed output.
| Name | Required | Description | Default |
|---|---|---|---|
| pids | Yes | List of process IDs to wait for (returned by the run tool). | |
| timeout | No | Optional: Maximum time to wait in seconds. Defaults to 180 (3 minutes). | |
| verbose | No | Optional: If true, each result item uses the full result shape including metadata fields and detailed parsed output. Defaults to false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries full responsibility. It discloses compact vs verbose defaults but omits behavior on timeout (error or partial results), failure handling, and side effects. Significant gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the core function and then explain key option. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details on return value shape (compact vs verbose), error handling for invalid pids or timeouts, and blocking behavior. With no output schema, completeness is insufficient for a 3-parameter tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value for the 'verbose' parameter (explains effect) but nothing new for 'pids' or 'timeout' beyond schema definitions. Marginal improvement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'wait' and the resource 'multiple AI agent processes'. It distinguishes from sibling tools like run, kill_process, and get_result by focusing on waiting for completion and returning results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied for after launching processes with run, but no explicit when-to-use or when-not-to-use guidance is given. Alternatives like get_result for individual results are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0cleanup_processesdoctorget_resultkill_processlist_processesmodelspeekrunwaitScored across 9 tools
Each tool targets a distinct lifecycle action: run starts, list_processes enumerates, get_result retrieves output, kill_process terminates, peek observes running agents, wait blocks for completion, cleanup_processes removes old entries, doctor checks CLI availability, and models lists supported models. No overlap in purpose.
Naming is mixed: some tools use verb_noun with underscores (cleanup_processes, kill_process, list_processes, get_result) while others are single verbs or nouns (doctor, models, peek, run, wait). This inconsistency reduces predictability, though each name is still descriptive.
With 9 tools, the server covers the essential operations for managing AI agent processes—start, monitor, retrieve, wait, kill, cleanup, plus auxiliary checks for setup and model info. Neither too few nor too many.
The tool set provides a complete lifecycle: creation (run), monitoring (list_processes, peek, wait), retrieval (get_result), termination (kill_process), cleanup (cleanup_processes), setup verification (doctor), and configuration (models). No obvious gaps for process management.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server for progressive tool usage at any scale (see https://klavis.ai)
