agent-bridge-mcp

A capability-aware MCP server and HTTP/WebSocket gateway for orchestrating interchangeable coding agents.

Agent Bridge treats each agent as an adapter behind a common runtime contract. The core router does not hard-code Claude, Codex, or Antigravity behavior; registered adapters advertise capabilities such as sessions, streaming, cancellation, model selection, sandbox control, file tools, and shell tools. Workflows may name a specific agent or select one by required capabilities.

Status: experimental. Interfaces may still change. The runtime is intended for trusted local development environments and should not be exposed to untrusted networks.

Architecture

MCP / HTTP / WebSocket
        |
        v
  SessionRouter
        |
        v
   AgentRegistry
        |
   AgentAdapter
   /    |       \
Claude Codex  Antigravity  ...
        |
        +--> TaskManager
        +--> SessionStore

WorkflowEngine ----> EvidenceGate ----> Git / tests / typecheck / lint
     |
     +--> ReviewLoop preset

The built-in adapters currently cover:

• Claude Code CLI

• Codex CLI

• Codex SDK

• Antigravity (agy) CLI

Additional agents can be added by implementing and registering another AgentAdapter; the core AgentType is not a closed union of built-in names.

Core concepts

Agent Registry and capabilities

Each registered adapter declares:

• sessions

• streaming

• cancellation

• models

• sandboxControl

• fileTools

• shellTools

Call agent_capabilities over MCP or GET /api/capabilities over HTTP to inspect what is available.

A workflow can select a concrete adapter:

- type: agent
  role: implementer
  agent: codex
  engine: cli

or request capabilities and let the registry choose:

- type: agent
  role: implementer
  requires:
    - sessions
    - fileTools
    - shellTools

Generic workflows

WorkflowEngine executes ordered role-based steps. An agent step can receive:

• {{input}}

• {{previousOutput}}

• {{evidenceSummary}}

• {{gitDiff}}

• {{testResults}}

Evidence steps are fail-closed: no verification commands means no verified PASS.

The older implement → evidence → review loop remains available as a compatibility preset on top of the generic workflow runtime. Implementer and reviewer are selectable registered agents rather than fixed core dependencies.

Sessions and tasks

Agent Bridge tracks internal sessions and external agent session/thread/conversation IDs. Matching considers agent, engine, workspace, project, topic, and task type. Explicit session reuse is rejected when the requested agent/engine/workspace is incompatible.

Every dispatch creates a task record with status, output, error, and exit code. Cancellation is terminal; late completion cannot resurrect a cancelled task.

Install

npm install -g @yukinuma/agent-bridge-mcp

Requires Node.js 20+ and whichever agent CLIs you intend to drive already installed and authenticated.

Antigravity on Windows

agy expects a real terminal. On Windows the adapter runs it under winpty when available and keeps stdin open for the call. It persists the returned conversation ID and resumes with --conversation on later turns.

Set WINPTY_PATH or AGY_PATH if either binary is in a non-standard location. Non-Windows Antigravity execution is not yet well tested.

Use as an MCP server

{
  "mcpServers": {
    "agent-bridge": {
      "command": "agent-bridge-mcp",
      "env": {
        "AGENT_BRIDGE_WORKSPACE": "/path/to/your/projects"
      }
    }
  }
}

MCP tools:

Use as an HTTP/WebSocket gateway

export ABC_AUTH_TOKEN="$(openssl rand -hex 24)"
export AGENT_BRIDGE_WORKSPACE="/path/to/your/projects"
agent-bridge-gateway

The gateway refuses to start without ABC_AUTH_TOKEN.

HTTP endpoints

Execution endpoints require an explicit cwd or project, and every resolved path must stay inside AGENT_BRIDGE_WORKSPACE.

Example generic workflow request:

{
  "project": "my-app",
  "input": "Implement the requested feature and verify it.",
  "workflow": {
    "steps": [
      {
        "type": "agent",
        "role": "implementer",
        "requires": ["fileTools", "shellTools", "sessions"],
        "prompt": "{{input}}"
      },
      {
        "type": "evidence",
        "role": "verifier",
        "testCommands": ["npm test", "npm run typecheck"]
      },
      {
        "type": "agent",
        "role": "reviewer",
        "agent": "claude",
        "prompt": "Review the implementation. Evidence: {{evidenceSummary}}\nDiff:\n{{gitDiff}}"
      }
    ]
  }
}

Evidence and review safety

Evidence verification is fail-closed. A reviewer cannot turn a failed or missing Evidence Gate into PASS merely by writing the word PASS. Review verdict parsing only accepts a verdict at the beginning of the first non-empty line.

Git commit and push results are tracked separately; a successful local commit with a failed push is reported as failure rather than success.

Security

This is a privileged local development daemon. Built-in unattended CLI adapters may disable approval/sandbox prompts so they do not hang waiting for input.

In particular:

Treat possession of the gateway token as equivalent to powerful local development access.

• Keep the default bind address at 127.0.0.1 unless you fully trust the network.

• Prefer the Authorization header over query-string tokens because query strings may be logged.

• All execution paths are constrained to AGENT_BRIDGE_WORKSPACE, but agents still execute with the privileges of the OS user running Agent Bridge.

• /api/git/commit-push pushes to the configured repository remote without a second interactive approval.

Do not expose the gateway to an untrusted network or run it under an unnecessarily privileged user.

Claude SDK status

The old ClaudeSdkAdapter used the plain Anthropic Messages API and therefore did not provide Claude Code/agent capabilities. That path has been removed. engine=sdk for Claude remains intentionally unavailable until a real Claude Agent SDK adapter is implemented.

Development and verification

npm install
npm run typecheck
npm run build
npm run test:hardening

CI runs typecheck, build, and hardening integration tests. A separate live E2E script validates real authenticated Claude/Codex/Antigravity session continuity when those CLIs are installed locally:

npm run test:agents:e2e

License

MIT