claude-mcp-bridge

claude-mcp-bridge

MCP server that wraps Claude Code CLI as a subprocess, exposing its capabilities as Model Context Protocol tools.

Works with any MCP client: Codex CLI, Gemini CLI, Cursor, Windsurf, VS Code, or any tool that speaks MCP.

Do you need this?

If you're in a terminal agent (Codex CLI, Gemini CLI) with shell access, call Claude Code CLI directly:

# Analyze specific files
claude -p --bare --tools Read -- "Analyze src/utils/parse.ts for edge cases"

# With budget cap
claude -p --bare --max-budget-usd 0.50 "Is this retry logic sound?"

--bare skips hooks, memory, and plugins for clean subprocess use. --tools restricts which tools Claude can use at all; --allowed-tools only pre-approves permission and leaves everything else, including Bash, still reachable. --max-budget-usd prevents runaway costs.

--tools is variadic, so end the list with -- (or another flag) before the prompt. Without it the prompt is read as one more tool name and the CLI exits with "Input must be provided".

For code review, see Code review with this CLI.

Use this MCP bridge instead when:

• Your client has no shell access (Cursor, Windsurf, Claude Desktop, VS Code)
• You need structured output with native --json-schema validation
• You need session resume across calls (--resume SESSION_ID)
• You need concurrency management and security hardening
• You want cost metadata surfaced in MCP responses

Quick Start

npx claude-mcp-bridge

Prerequisites

• Claude Code CLI installed and on PATH
• Authentication (one of):
  • Subscription (default): claude login (uses your Pro/Max plan, no API credits needed)
  • API key: set ANTHROPIC_API_KEY + CLAUDE_BRIDGE_USE_API_KEY=1 (billed per use via console.anthropic.com)

Codex CLI

Add to ~/.codex/config.json:

{
  "mcpServers": {
    "claude-bridge": {
      "command": "npx",
      "args": ["-y", "claude-mcp-bridge"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "claude-bridge": {
      "command": "npx",
      "args": ["-y", "claude-mcp-bridge"]
    }
  }
}

Cursor / Windsurf / VS Code

Add to your MCP settings:

{
  "claude-bridge": {
    "command": "npx",
    "args": ["-y", "claude-mcp-bridge"],
    "env": {
      "ANTHROPIC_API_KEY": "sk-ant-...",
      "CLAUDE_BRIDGE_USE_API_KEY": "1"
    }
  }
}

Tools

Tool	Description
query	Execute prompts with file context, session resume, effort control, and budget caps. Supports text and images. For code review, see Code review with this CLI.
search	Web search via Claude CLI's WebSearch and WebFetch tools. Returns synthesized answers with sources.
structured	JSON Schema validated output via Claude CLI's native --json-schema.
ping	Health check with CLI version, auth method, capabilities, and model config.
listSessions	List active sessions with cumulative cost, turn count, and timestamps.

query

Execute a prompt with optional file context. Supports session resume via sessionId, effort control (low/medium/high/max), and budget caps (maxBudgetUsd). Images (.png, .jpg, .gif, .webp, .bmp) up to 5MB each are passed to Claude's Read tool.

Key parameters: prompt (required), files, model (default sonnet), sessionId, effort, maxBudgetUsd, workingDirectory, timeout (default 60s).

search

Web search powered by Anthropic's WebSearch tool via Claude CLI. Returns synthesized answers with source URLs.

Key parameters: query (required), model (default sonnet), maxResponseLength, maxBudgetUsd, timeout (default 120s).

structured

Generate JSON conforming to a provided schema using Claude CLI's native --json-schema flag. Returns clean JSON in the first content block, metadata in a separate block so JSON parsing isn't broken.

Key parameters: prompt (required), schema (required, JSON string, max 20KB), files, model (default sonnet), sessionId, maxBudgetUsd, timeout (default 60s).

ping

No parameters. Returns CLI version, auth method (subscription/api-key/none), configured models, capabilities, and server version.

listSessions

No parameters. Returns active sessions with metadata: sessionId, model, createdAt, lastUsedAt, turnCount, totalCostUsd.

All tools attach execution metadata (_meta) with durationMs, model, sessionId, totalCostUsd, and token breakdowns. See DESIGN.md for details.

Configuration

Models

Variable	Default	Description
CLAUDE_DEFAULT_MODEL		Shared default for all tools
CLAUDE_QUERY_MODEL	sonnet	Default for query
CLAUDE_STRUCTURED_MODEL	sonnet	Default for structured
CLAUDE_SEARCH_MODEL	sonnet	Default for search
CLAUDE_FALLBACK_MODEL	haiku	Fallback on quota exhaustion (none to disable)

Model resolution: explicit parameter > tool-specific env var > CLAUDE_DEFAULT_MODEL > built-in default.

Runtime

Variable	Default	Description
CLAUDE_MAX_CONCURRENT	3	Max concurrent subprocess spawns
CLAUDE_CLI_PATH	claude	Path to CLI binary
CLAUDE_MAX_BUDGET_USD		Global cost cap in USD (per call)
ANTHROPIC_API_KEY		API key (only forwarded when CLAUDE_BRIDGE_USE_API_KEY=1)
CLAUDE_BRIDGE_USE_API_KEY		Set to 1 to forward ANTHROPIC_API_KEY to the subprocess (default: subscription auth)

Effort

Variable	Default	Description
CLAUDE_SEARCH_EFFORT	medium	Default effort for search
CLAUDE_QUERY_EFFORT		Default effort for query

Tools

Each spawned subprocess gets an explicit built-in toolset. The defaults are read-only, so Bash, Write and Edit are not granted unless you widen them below.

Variable	Default	Description
CLAUDE_QUERY_TOOLS	Read Glob Grep	Built-in tools for query
CLAUDE_STRUCTURED_TOOLS	Read Glob Grep	Built-in tools for structured
CLAUDE_SEARCH_TOOLS	WebSearch WebFetch	Built-in tools for search

Accepts a comma or space separated list, default for the CLI's full built-in set, or an empty value for no tools. Widening these gives the subprocess real capability in the working directory you pass it. See SECURITY.md § Tool Sandboxing.

Choosing a Claude Code MCP server

You need...	Consider
Structured output, effort/budget control, session resume, cost metadata	This bridge
Multi-tool orchestration (read, grep, edit, bash as separate MCP tools)	mcp-claude-code
Session continuity with async execution	claude-mcp
Maintained lightweight wrapper	@kunihiros/claude-code-mcp
Native Claude Code MCP (built-in, no wrapper)	claude mcp serve (docs)

Performance

Claude Code CLI has minimal startup overhead. Wall time is dominated by model inference and any agentic exploration.

Scenario	Typical time
Trivial prompt (sonnet)	5-10s
Web search + synthesis	15-30s

Cost metadata (totalCostUsd, token breakdowns) is returned in _meta on every response.

Bridge family

Two MCP servers, same architecture, different underlying CLIs. Each wraps a terminal agent as a subprocess and exposes it as MCP tools. Pick the one that matches your model provider, or run both for cross-model workflows.

	claude-mcp-bridge	codex-mcp-bridge
CLI	Claude Code	Codex CLI
Provider	Anthropic	OpenAI
Tools	query, search, structured, ping, listSessions	codex, search, query, structured, ping, listSessions
Code review	Use Claude Code built-ins directly (not via this bridge), or claude -p for non-Claude-Code hosts	codex review --base <ref> (native) or codex tool with caller-supplied prompt
Structured output	Native --json-schema (no Ajv)	Ajv validation
Session resume	Native --resume	Session IDs with multi-turn
Budget caps	Native --max-budget-usd	Not supported
Effort control	--effort low/medium/high/max	Not supported
Cold start	~1-2s	<100ms (inference dominates)
Auth	claude login (default) or ANTHROPIC_API_KEY + opt-in	OPENAI_API_KEY
Cost	Subscription (default) or API credits (opt-in)	Pay-per-token
Concurrency	3 (configurable)	3 (configurable)
Model fallback	Auto-retry with fallback model	Auto-retry with fallback model

Both share: subprocess env isolation, path sandboxing, output redaction, FIFO concurrency queue, MCP tool annotations, _meta response metadata, progress heartbeats.

Code review with this CLI

The reviewer prompt is supplied by the caller. The bridge does not bundle review prompts (see ADR-001).

• In Claude Code (interactive REPL): use the built-in /review, /security-review, /ultrareview. REPL-only; not reachable via claude -p or this bridge.
• Through this bridge (query / structured): pass the review prompt as plain text. Slash commands (built-in or user-installed ~/.claude/commands/) do not resolve through the bridge, the isolation flags (--bare on the API-key path, --setting-sources "" on the subscription path) block all skill resolution by design. Tracked upstream: anthropics/claude-code#37207.
• Direct claude -p (no bridge): user skills resolve as /skill-name when no isolation flags suppress them. For subprocess-isolated review use the hardened invocation below.

Route based on where you are:

• Already in Claude Code? Type /review, /security-review, or /ultrareview. Skip the rest of this section.
• Calling from another MCP host (Cursor, Codex CLI, Gemini CLI, Claude Desktop)? Slash commands and skills are not reachable through the bridge. Pass your review prompt as plain text to query / structured, or invoke claude -p directly per below.

Direct claude -p invocation (subprocess-isolated)

For shell-equipped consumers (terminal agents, CI, BYOS skills), invoke the CLI directly with hardened isolation flags:

claude -p \
  --permission-mode plan \
  --bare \
  --add-dir <repo-root> \
  --strict-mcp-config \
  --mcp-config '{"mcpServers":{}}' \
  --no-session-persistence \
  --max-budget-usd 0.50 \
  "<your review prompt + diff or file references>"

• --permission-mode plan: read-only.
• --bare: strips parent's hooks, plugins, auto-memory, and CLAUDE.md autoload.
• --add-dir <repo-root>: makes the repo's CLAUDE.md / AGENTS.md available where the diff warrants it.
• --strict-mcp-config --mcp-config '{"mcpServers":{}}': blocks parent's MCP servers from leaking in. The inner mcpServers key is required; the schema rejects bare '{}'.
• --no-session-persistence: no session files for one-off reviews.
• --max-budget-usd: per-call cost cap.

Claude Code skill template

For Claude Code users who want a reusable command, drop this into ~/.claude/commands/review-claude.md:

---
description: Code review via subprocess-isolated claude -p
---

Run code review on the diff between origin/main and HEAD.

```bash
claude -p \
  --permission-mode plan \
  --bare \
  --add-dir "$(git rev-parse --show-toplevel)" \
  --strict-mcp-config \
  --mcp-config '{"mcpServers":{}}' \
  --no-session-persistence \
  --max-budget-usd 0.50 \
  "Review the diff below for bugs, missing error handling on user input, tests modified to silence failures, and security issues (injection, missing auth checks, secret leaks). For each finding cite file:line, severity, and a suggested fix. Skip style/formatting.

$(git diff origin/main...HEAD)"
```

Representative review prompt

A starting point; adapt freely:

Review the following diff:

<diff content>

Look for:
- Bugs that would surface in production
- Missing error handling on user-supplied input
- Tests modified to silence failures rather than verify behaviour
- Security issues (injection, missing auth checks, secret leaks)

For each finding cite file:line, severity (high/medium/low), and a suggested fix.
Skip style/formatting; assume an autoformatter handles those.

Development

npm install
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm test             # Run tests (vitest)
npm run lint         # ESLint
npm run typecheck    # tsc --noEmit
npm run smoke        # Smoke test against live CLI

Further reading

• DESIGN.md - Architecture, sessions, cost tracking, response metadata, progress notifications
• SECURITY.md - Environment isolation, path sandboxing, output redaction, tool sandboxing
• CHANGELOG.md - Release history

License

MIT