mcp-agents

MCP server that wraps AI CLI tools — Claude Code, Gemini CLI, and Codex CLI — so any MCP client can call them as tools.

Prerequisites

• Node.js >= 18
• At least one of the following CLIs installed and on your $PATH:

CLI	Install
claude	Claude Code docs
gemini	npm install -g @anthropic-ai/gemini-cli
codex	npm install -g @openai/codex

Only the CLI you select with --provider needs to be present.

Install

npm install -g mcp-agents

Global install is strongly recommended over npx -y mcp-agents@latest. The npx approach performs a network round-trip on every cold start, which can exceed MCP client connection timeouts and cause "stream disconnected" errors.

Tip: If your project's .mcp.json references mcp-agents, add npm install -g mcp-agents to your setup script (e.g. bin/setup) so new developers get it automatically.

Quick test

# Default provider (codex)
mcp-agents

# Specific provider
mcp-agents --provider claude
mcp-agents --provider gemini

# Optional: enable Gemini sandbox mode
mcp-agents --provider gemini --sandbox true

The server speaks JSON-RPC over stdio. It prints [mcp-agents] ready (provider: <name>) to stderr when it's listening.

Providers & Tools

Each --provider flag maps to a single exposed tool:

Provider	Tool name	CLI command
claude	claude_code	claude -p --output-format json
gemini	gemini	gemini [-s] -p <prompt>
codex	(pass-through)	codex mcp-server

claude_code parameters

Parameter	Type	Required	Description
prompt	string	yes	The prompt to send to Claude Code
timeout_ms	integer	no	Timeout in ms (default: 300 000 / 5 minutes)

Any additional tools/call arguments are ignored (for example model or model_reasoning_effort).

Claude calls run with --output-format json; the server parses the JSON payload and returns the assistant result text (or an MCP error if is_error=true).

gemini parameters

Parameter	Type	Required	Description
prompt	string	yes	The prompt to send to Gemini CLI
sandbox	boolean	no	Run in sandbox mode (-s flag, default: false)
timeout_ms	integer	no	Timeout in ms (default: 300 000 / 5 minutes)

Any additional tools/call arguments are ignored (for example model or model_reasoning_effort).

codex (pass-through)

The codex provider passes through to Codex's native MCP server (codex mcp-server) inside an isolated CODEX_HOME. The bridge copies auth.json into a temporary Codex home, writes a minimal config.toml, and does not inherit your normal external MCP server list. That keeps Codex from recursively starting other agent tools like Claude or Gemini during bridge calls.

CLI Flag	Default	Codex config key
--model	gpt-5.4	model
--model_reasoning_effort	xhigh	model_reasoning_effort

Hardcoded defaults: sandbox_mode=read-only, approval_policy=never, features.multi_agent=false.

Startup flags set server-wide defaults for the native Codex MCP server. Per-call overrides still work through the native codex tool schema, for example:

{
  "prompt": "Review this diff",
  "config": {
    "model_reasoning_effort": "medium"
  }
}

Integration with Claude Code

Add entries to your project's .mcp.json (requires npm i -g mcp-agents):

{
  "mcpServers": {
    "codex": {
      "command": "mcp-agents",
      "args": ["--provider", "codex"]
    },
    "gemini": {
      "command": "mcp-agents",
      "args": ["--provider", "gemini"]
    }
  }
}

Optional Gemini sandbox mode in .mcp.json:

{
  "mcpServers": {
    "gemini": {
      "command": "mcp-agents",
      "args": ["--provider", "gemini", "--sandbox", "true"]
    }
  }
}

Override codex defaults at server startup:

{
  "mcpServers": {
    "codex": {
      "command": "mcp-agents",
      "args": ["--provider", "codex", "--model", "gpt-5.4", "--model_reasoning_effort", "medium"]
    }
  }
}

The startup default can still be overridden for a single Codex tool call by passing config.model_reasoning_effort to the native codex tool.

Because the bridge runs in an isolated Codex home, inherited MCP servers from your normal ~/.codex/config.toml are intentionally unavailable inside bridged Codex sessions.

Alternative: using npx (slower, not recommended)

{
  "mcpServers": {
    "codex": {
      "command": "npx",
      "args": ["-y", "mcp-agents@latest", "--provider", "codex"]
    }
  }
}

Warning: npx -y mcp-agents@latest performs a network round-trip on every cold start (~70s), which can exceed MCP client connection timeouts.

Integration with OpenAI Codex

Add two entries to ~/.codex/config.toml — one per provider you want available. Set tool_timeout_sec = 300 to avoid Codex MCP's default 60s per-tool timeout:

[mcp_servers.claude-code]
command = "mcp-agents"
args = ["--provider", "claude"]
tool_timeout_sec = 300

[mcp_servers.gemini]
command = "mcp-agents"
args = ["--provider", "gemini"]
tool_timeout_sec = 300

Optional Gemini sandbox mode in Codex config:

[mcp_servers.gemini]
command = "mcp-agents"
args = ["--provider", "gemini", "--sandbox", "true"]
tool_timeout_sec = 300

Then in a Codex session you can call the claude_code or gemini tools, which shell out to the respective CLIs.

Development

npm install
npm link          # symlinks mcp-agents to your local server.js

After npm link, any edits to server.js take effect immediately — no reinstall needed.

How it works

1. An MCP client connects over stdio
2. The server reads --provider <name> from its argv (defaults to codex)
3. It registers a single tool matching that provider's CLI
4. Client calls tools/call with the tool name and a prompt
5. The server runs the CLI as a child process and returns tool text (Claude JSON result, or stdout/stderr for other providers)

The server keeps a small keepalive timer so Node.js does not exit prematurely when stdin reaches EOF before an async subprocess registers an active handle. For Claude and Gemini provider mode, that keepalive is cleared during shutdown: the server now exits when the MCP stdio connection closes and kills any tracked detached provider child process groups that would otherwise linger.

License

MIT