MCP Workflow CLI Bridge

A local Model Context Protocol (MCP) server that acts as a unified dispatch hub, routing tasks to various coding agent CLIs installed on your local machine (claude, codex, opencode, gemini, agy).

It provides capability-based routing, CLI availability discovery, strict JSON Schema output validation, automatic execution retries, and a normalized response envelope.

Table of Contents

• Problem & Context

• How It Works

• Supported Providers & Capabilities

• Installation & Client Configuration

  • Claude Desktop

  • Claude Code

  • Codex Plugin

  • Cursor / Windsurf

• MCP Tools Spec

  • code_cli_bridge.providers

  • code_cli_bridge.run_agent

• Routing Configuration

• Security & Sandbox Guidelines

• Development & Testing

• Contributing

• Changelog

Related MCP server: MCP Gateway

Problem & Context

Claude Code Dynamic Workflows (.claude/workflows/*.js) and other MCP clients often need to delegate sub-tasks to specialized CLI engines—e.g., Codex for structured output with image analysis, or OpenCode for lightweight generation—without hardcoding provider-specific APIs or rewriting execution logic for each different client environment.

The MCP Workflow CLI Bridge solves this by abstracting local CLI tool execution behind a standardized MCP interface.

How It Works

Claude Dynamic Workflow (.claude/workflows/*.js)
  -> agent() call with agentType: "workflow-cli-router"
  -> .claude/agents/workflow-cli-router.md (Claude subagent)
  -> MCP tool: code_cli_bridge.run_agent
  -> broker: routing + schema validation + retry
  -> provider adapter (claude | codex | opencode | gemini | agy)
  -> local CLI process
  -> normalized response envelope

Supported Providers & Capabilities

Below is the capabilities matrix for the supported local CLI engines:

If a call requires a capability the target provider does not support (e.g., passing a schema to agy), the broker rejects the request with a validation error before spawning any process.

Installation & Client Configuration

Prerequisites

• Node.js >= 20.19.4

• Local installation of the CLI engines you plan to use (e.g., claude, codex, etc.) available on your system PATH.

git clone https://github.com/mateusoliveirab/mcp-workflow-cli-bridge.git
cd mcp-workflow-cli-bridge
npm install

1. Claude Desktop

Add the server configuration to your claude_desktop_config.json:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-workflow-cli-bridge": {
      "command": "node",
      "args": ["--import", "tsx", "/absolute/path/to/mcp-workflow-cli-bridge/src/mcp-server.ts"]
    }
  }
}

2. Claude Code

To use this inside Claude Code, define the server in your project's local .mcp.json configuration file:

{
  "mcpServers": {
    "mcp-workflow-cli-bridge": {
      "cwd": ".",
      "command": "node",
      "args": ["--import", "tsx", "/absolute/path/to/mcp-workflow-cli-bridge/src/mcp-server.ts"]
    }
  }
}

Then, create .claude/agents/workflow-cli-router.md to map agent work to code_cli_bridge.run_agent.

3. Codex Plugin

You can add the bridge directly as a Codex plugin:

codex plugin marketplace add /path/to/mcp-workflow-cli-bridge
codex plugin add mcp-workflow-cli-bridge@mcp-workflow-cli-bridge-local

4. Cursor / Windsurf

In Cursor/Windsurf, navigate to Settings -> Features -> MCP and add a new MCP Server:

• Name: mcp-workflow-cli-bridge

• Type: command

• Command: node --import tsx /absolute/path/to/mcp-workflow-cli-bridge/src/mcp-server.ts

MCP Tools Spec

code_cli_bridge.providers

Returns all registered provider adapters, their capabilities, and whether their CLI binaries are available on the user's PATH.

code_cli_bridge.run_agent

Runs a task on the targeted provider.

Parameters:

Example Call:

{
  "workflow": "blog-pipeline",
  "phase": "Generate",
  "label": "generate:iter1",
  "cwd": "/path/to/project",
  "prompt": "Generate a blog post about TypeScript performance",
  "provider": "codex",
  "schema": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "body": { "type": "string" }
    },
    "required": ["title", "body"]
  }
}

Routing Configuration

Create a route-config.json at your repository root to govern automatic tool execution routing:

{
  "defaultProvider": "opencode",
  "routes": [
    { "phase": "Extract", "provider": "codex" },
    { "phase": "Generate", "provider": "opencode" }
  ]
}

If no route configuration matches, the broker will auto-select a provider only if exactly one available CLI satisfies the requested capabilities.

Security & Sandbox Guidelines

Development & Testing

Run the local test suite using:

npm install
npm test          # Runs 50 deterministic tests via node:test
npm run typecheck # Strict TypeScript check

Validate provider connectivity without spawning actual CLI tasks:

npm run smoke

Validate live provider adapters (requires the corresponding CLI binaries installed and configured):

npm run live:validate
npm run live:validate:claude

Contributing

See our CONTRIBUTING.md for detailed guidelines on developer setup, coding styles, and test validations.

Changelog

For a full list of changes and releases, see CHANGELOG.md.