Purpose
claude-mcp-bridge is an MCP server that wraps the Claude Code CLI as a subprocess and exposes its capabilities as Model Context Protocol tools. It works with any MCP-capable client, including Codex CLI, Gemini CLI, Cursor, Windsurf, VS Code, and others.
When to use
If you are in a terminal agent with shell access (such as Codex CLI or Gemini CLI), you can call the Claude Code CLI directly. When calling directly, you can use --bare to skip hooks, memory, and plugins for a clean subprocess;--tools to limit the tools Claude can use;--allowed-tools to pre-approve only permissions, while other tools (including Bash) remain reachable;--max-budget-usd to prevent runaway costs. Note that --tools is variadic, and the list must be terminated before the prompt with --(or another flag), otherwise the prompt will be treated as just another tool name and the CLI will exit with "Input must be provided".
Use this MCP bridge instead in the following cases: the client has no shell access (Cursor, Windsurf, Claude Desktop, VS Code); you need structured output with native --json-schema validation; you need to resume sessions across calls (--resume SESSION_ID); you need concurrency management and security hardening; you want to expose cost metadata in MCP responses.
Prerequisites
The Claude Code CLI must be installed and on PATH. Choose one of two authentication methods: subscription (default) uses claude login, going through a Pro/Max plan with no API credits required; the API key method requires setting ANTHROPIC_API_KEY and CLAUDE_BRIDGE_USE_API_KEY=1, billed by usage via console.anthropic.com.
Configuration
For Codex CLI, add to ~/.codex/config.json; for Gemini CLI, add to ~/.gemini/settings.json; for Cursor / Windsurf / VS Code, add to their respective MCP settings.
Main tools
query: Executes a prompt and can include file context. Supports resuming sessions via sessionId , effort control (low / medium / high / max), and a budget cap (maxBudgetUsd). Images (.png, .jpg, .gif, .webp, .bmp) are up to 5MB each and are passed to Claude's Read tool. Key parameters:prompt(required),files、model(default sonnet),sessionId、effort、maxBudgetUsd、workingDirectory、timeout(default 60s).
search: Provides web search via Anthropic's WebSearch tool through the Claude CLI, returning a synthesized answer with source URLs. Key parameters:query(required),model(default sonnet),maxResponseLength、maxBudgetUsd、timeout(default 120s).
structured: Uses the Claude CLI's native --json-schema flag to generate JSON conforming to the provided schema. Clean JSON is placed in the first content block, and metadata is placed in a separate block so as not to break JSON parsing. Key parameters:prompt(required),schema(required, JSON string, max 20KB),files、model(default sonnet),sessionId、maxBudgetUsd、timeout(default 60s).
status: No parameters. Returns the CLI version, authentication method (subscription/api-key/none), configured models, capabilities, and server version.
sessions: No parameters. Returns active sessions and their metadata:sessionId、model、createdAt、lastUsedAt、turnCount、totalCostUsd.
All tools include execution metadata (_meta), containing durationMs、model、sessionId、totalCostUsd and token details.
Model resolution and tool sandbox
Model resolution priority: explicit parameters > tool-specific environment variables > CLAUDE_DEFAULT_MODEL > built-in defaults.
Each spawned subprocess receives an explicit built-in tool set. The default is read-only; unless the configuration is relaxed, Bash, Write, and Edit will not be granted. The tool set accepts a comma- or space-separated list; the default value is the CLI's full built-in set, and an empty value means no tools are granted. Relaxing these settings gives the subprocess real capabilities in the working directory you pass in.
Comparison with other Claude Code MCP servers
The Claude Code CLI has very low startup overhead; actual time is mainly determined by model inference and agent exploration. Cost metadata (totalCostUsd, token details) is returned in each response's _meta . The two MCP servers have the same architecture but different underlying CLIs; each wraps a terminal agent as a subprocess and exposes it as an MCP tool. You can choose based on model provider, or run both to support cross-model workflows. Both share: subprocess environment isolation, path sandboxing, output redaction, FIFO concurrency queue, MCP tool annotations,_meta response metadata, progress heartbeat.
Code review
The review prompt is provided by the caller; the bridge itself does not bundle a review prompt. In the Claude Code interactive REPL, you can use the built-in /review、/security-review、/ultrareview, but these are REPL-only and cannot be reached through claude -p or this bridge. When going through this bridge (query / structured), the review prompt must be passed in as plain text; slash commands (built-in or user-installed in ~/.claude/commands/) are not resolved through the bridge, and the isolation flags ( --barefor the API key path, --setting-sources ""for the subscription path) block all skill resolution by design. When using claude -pdirectly (without the bridge), user skills are resolved as /skill-name unless suppressed by isolation flags.
Direct claude -p invocation (subprocess isolation) is suitable for consumers with a shell (terminal agents, CI, BYOS skills), and can use hardened isolation flags:--permission-mode plan(read-only),--bare(strips the parent process's hooks, plugins, auto-memory, and CLAUDE.md auto-loading),--add-dir <repo-root>(makes the repository's CLAUDE.md / AGENTS.md available when the diff requires it),--strict-mcp-config --mcp-config '{"mcpServers":{}}'(prevents the parent process's MCP servers from leaking in; the internal mcpServers key is required, and the schema rejects bare {}）、--no-session-persistence(one-off reviews do not retain session files),--max-budget-usd(per-call cost cap).
Applicable scenarios and limitations
Suitable for MCP clients without shell access, scenarios requiring structured output and session recovery, requiring concurrency management and security hardening, and wanting cost metadata in responses. Limitations include: slash commands and skills cannot be resolved through the bridge; the tool sandbox is read-only by default and must be explicitly relaxed to gain write capabilities; the structured output schema is at most 20KB; images are at most 5MB each.
