Skip to main content
Glama

agent-bridge-mcp

MCP-only server for running local Claude, Codex, Forge, OpenCode, and Antigravity CLI agents as background jobs.

License: MIT Node.js MCP

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-mcp

Why This Exists

Most 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

What It Is Not

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.

Supported Agent CLIs

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.

Requirements

  • Node.js ^20.19.0 || >=22.12.0

  • npm

  • At least one supported AI CLI installed locally

  • An MCP client that supports stdio servers

Installation

From Source

git clone https://github.com/lailai258/agent-bridge-mcp.git
cd agent-bridge-mcp
npm install
npm run build

Start the built MCP server:

npm start

Development mode:

npm run dev

From npm

If installed from npm, the package name is:

npm install -g agent-bridge-mcp-server

Then start the stdio server with:

agent-bridge-mcp

MCP Client Configuration

Use 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.

Quick Example

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
}

MCP Tools

All tool responses are returned as MCP text content containing pretty-printed JSON.

run

Starts 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_processes

Lists tracked processes from current server memory plus the persisted process registry:

  • pid

  • agent

  • status

Statuses are running, completed, or failed.

get_result

Returns 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.

wait

Waits 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.

peek

Observes 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_process

Sends SIGTERM to a running process by PID.

cleanup_processes

Removes completed and failed process records from the server's in-memory process table and persisted registry. Log files are left on disk for troubleshooting.

doctor

Reports 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.

models

Lists supported model names, aliases, Antigravity entrypoint, and OpenCode dynamic model syntax.

Models

Aliases

  • claude-ultra -> Claude opus, with default reasoning_effort=max

  • codex-ultra -> Codex gpt-5.5, with default reasoning_effort=xhigh

Standard Models

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

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.

Session Resume

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.

CLI Path Configuration

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-mcp

Architecture

MCP 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 / agy

Core modules:

Runtime State

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.

Security Notes

  • 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.

Development

Install dependencies:

npm install

Build:

npm run build

Run unit tests:

npm run test:unit

Run the full test suite:

npm test

Check package contents before publishing:

npm_config_cache="/private/tmp/agent-bridge-mcp-npm-cache" npm pack --dry-run

Documentation

Additional project documentation:

License

MIT. See LICENSE.

Available Tools

9 tools
cleanup_processesA

Remove all completed and failed processes from the process list to free up memory.

Inputs: no named parameters.

doctorA

Check supported AI CLI binary availability and path resolution. Does not verify login state or terms acceptance.

Inputs: no named parameters.

get_resultA

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.

Inputs: pid (required), verbose.

kill_processC

Terminate a running AI agent process by PID.

Inputs: pid (required).

list_processesA

List all running and completed AI agent processes. Returns a simple list with PID, agent type, and status for each process.

Inputs: no named parameters.

modelsA

List supported model names, model aliases, and dynamic backend discovery hints.

Inputs: no named parameters.

peekA

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.

Inputs: pids (required), peek_time_sec, include_tool_calls.

runA

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

  1. Be concise, explicit & step-by-step for complex tasks.

  2. Check process status with list_processes

  3. Get results with get_result using the returned PID

  4. Kill long-running processes with kill_process if needed

Inputs: workFolder (required), prompt, prompt_file, model, +2 more.

waitB

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.

Inputs: pids (required), timeout, verbose.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation5/5

    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 Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers