Consult

MCP server orchestrating local CLI agents (Claude Code, OpenAI Codex, Google Gemini) for cross-validation, second opinions, and persona-driven prompting.

What it does

When you're working in Claude Code (or any MCP client), consult-mcp lets you ask other LLM CLIs for their take — without leaving the conversation. Use cases:

• Second opinion: "Claude wrote this — what does Gemini think?"
• Cross-validation: send the same question to claude/codex/gemini in parallel and compare
• Variant generation: pass ["claude", "claude"] for two independent responses to the same prompt
• Specialized framing: apply a persona (architect, reviewer, researcher, coder) to focus the model

Eighteen MCP tools ship in v0.10:

• Read-only single-shot (no file mutation, return immediately):
  • consult(agent, prompt, persona?, timeout_seconds?) — single agent
  • consult_parallel(agents, prompt, persona?, timeout_seconds?) — fan-out to N agents
  • codereview(agents, files, focus?, timeout_seconds?) — multi-agent code review with structured findings
  • consensus(agents, question, stances?, synthesizer?, timeout_seconds?) — multi-agent verdict with optional stance steering
  • challenge(agent, claim, timeout_seconds?) — anti-sycophancy single-agent pushback
• Async debate (returns debate_id immediately, runs in background):
  • debate_start(agents, topic, max_turns?, history_window?, terminator?, ...) — kick off round-robin debate
  • debate_status(debate_id) — poll progress + transcript
  • debate_cancel(debate_id) — request soft cancellation
  • debate_list(active_only?, limit?) — list active + archived debates
  • debate_replay(debate_id) — full transcript from memory or SQLite archive
  • debate_export(debate_id, format?, truncate_body_chars?) — render archived debate as portable markdown (default) or stable v1 JSON for Obsidian/Notion/programmatic consumers
• Synchronous streaming debate (foreground call with progress notifications):
  • debate_run(agents, topic, max_turns?, ...) — returns when the loop terminates; pushes per-turn progress to MCP clients that honour progressToken (e.g. Claude Code). Non-resumable — for long debates use debate_start + poll instead
• Atomic deliberation (3-stage in one call):
  • council(agents, question, chairman?, persona?, timeout_seconds?) — independent → cross-rank (anonymized) → synthesis
• Niche (focused single-purpose tools):
  • planner(agent, problem, depth?, timeout_seconds?) — structured task decomposition (JSON tasks with dependencies)
  • diff_review(agents, diff_text?|git_ref?, cwd?, focus?, ...) — review a git diff for risks/regressions
  • apilookup(query, agent?, timeout_seconds?) — current docs lookup with web search (default agent: gemini)
• File-mutating (activates CLI permission/sandbox bypass flags):
  • implement(agent, plan, base_path, constraints?, timeout_seconds?) — delegate code changes; returns diff
  • delegate_implementation(task, base_path, planner_agent?, implementer_agent?, reviewer_agents?, ...) — composite plan→implement→review in one call. Plan via planner_agent, write code via implementer_agent (mutation rights, same CONSULT_MCP_ALLOWED_BASE guard), then fan-out to reviewer_agents (auto-routes to diff_review for git diffs or codereview for mtime-mode workspaces). Default reviewers exclude the implementer.

Prerequisites

• Python 3.10+ (the server itself)
• uv for installation (pipx install uv or follow astral.sh/uv)
• At least one of these CLI tools installed and authenticated:
  • Claude Code CLI — install via claude.com/code, then claude login
  • OpenAI Codex CLI — npm install -g @openai/codex, set OPENAI_API_KEY
  • Google Gemini CLI — install via geminicli.com, authenticate per docs

You don't need all three — consult-mcp reports per-agent status and skips missing CLIs.

API keys

Each CLI handles its own auth. Common env-var setup:

Platform	Set env var
Windows (PowerShell, persistent)	setx OPENAI_API_KEY "sk-..."
Windows (current shell)	$env:OPENAI_API_KEY = "sk-..."
macOS / Linux (current shell)	export OPENAI_API_KEY="sk-..."
macOS / Linux (persistent)	append export OPENAI_API_KEY="sk-..." to ~/.bashrc or ~/.zshrc

Replace OPENAI_API_KEY with GEMINI_API_KEY for Gemini. Claude Code uses interactive login (claude login); no env var.

Installation

Add this to your MCP client's configuration. For Claude Code, that's .mcp.json (project-local) or ~/.claude.json (global):

{
  "mcpServers": {
    "consult": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oblogin/consult-mcp.git",
        "consult-mcp"
      ]
    }
  }
}

Restart your MCP client. All six tools (consult, consult_parallel, codereview, consensus, challenge, implement) should appear.

A copy-pasteable snippet is in examples/.mcp.json.

Quick start

// Single-agent consultation:
consult({
  "agent": "gemini",
  "prompt": "Should we use GAS for an inventory system in Unreal Engine?",
  "persona": "architect"
})
// → {
//     "status": "success",
//     "agent": "gemini",
//     "persona": "architect",
//     "response": "GAS overkill for simple inventory; trade-offs ...",
//     "metadata": { "duration_seconds": 8.4, "returncode": 0 }
//   }

// Parallel cross-validation:
consult_parallel({
  "agents": ["claude", "codex", "gemini"],
  "prompt": "Reply with just the digit: what is 2+2?",
  "persona": "default"
})
// → {
//     "status": "success",
//     "responses": [
//       { "agent": "claude", "status": "success", "response": "4", ... },
//       { "agent": "codex",  "status": "success", "response": "4", ... },
//       { "agent": "gemini", "status": "success", "response": "4", ... }
//     ],
//     "summary": { "total": 3, "succeeded": 3, "failed": 0, "wall_time_seconds": 9.1, "max_duration_seconds": 8.4 }
//   }

Specialized tools (v0.2)

codereview — multi-agent code review

codereview({
  "agents": ["codex", "gemini"],
  "files": ["src/auth.py", "src/auth_test.py"],
  "focus": "auth and session handling"
})
// → { "status": "success",
//     "reviews": [
//       { "agent": "codex", "status": "success", "response": "...",
//         "findings": [
//           {"severity": "high", "location": "src/auth.py:42",
//            "title": "Missing CSRF check", "description": "..."}
//         ]},
//       { "agent": "gemini", ... }
//     ],
//     "summary": { "succeeded": 2, ... } }

Each agent is invoked with the reviewer persona, which instructs it to return JSON {summary, findings: [{severity, location, title, description}]}. The tool parses that JSON; on parse failure, the raw response stays in reviews[i].response with a metadata.findings_parse_error flag.

consensus — multi-agent verdict with stance steering

consensus({
  "agents": ["claude", "codex", "gemini"],
  "question": "Should we adopt SQLite WAL mode for our writes?",
  "stances": ["for", "against", "neutral"],
  "synthesizer": "claude"
})
// → { "votes": [{...}, {...}, {...}],
//     "synthesis": { "agent": "claude", "response": "Both sides agree..." } }

Stances (for/against/neutral) prefix each agent's prompt. Optional synthesizer runs once more after the votes to produce a verdict.

challenge — anti-sycophancy pushback

challenge({
  "agent": "claude",
  "claim": "Premature optimization is always wrong; ignore performance until benchmarks fail."
})
// → { "agent": "claude", "persona": "skeptic",
//     "response": "Counter: in real-time loops, even microseconds matter; ..." }

Persona is hardcoded to skeptic. The agent is instructed to find weaknesses and counter-arguments rather than agree.

implement — delegate code changes ⚠️ mutation-capable

implement({
  "agent": "codex",
  "plan": "Add a /healthz endpoint to api/server.py returning {\"ok\": true}.",
  "base_path": "F:/repos/my-app",
  "constraints": "Don't modify tests/. Use existing FastAPI app."
})
// → { "status": "success",
//     "mode": "git",
//     "files_modified": ["api/server.py"],
//     "files_created": [],
//     "diff": { "text": "...", "stat": "1 file changed, 5 insertions(+)", ... } }

This tool activates CLI mutation flags (--permission-mode acceptEdits, --dangerously-bypass-approvals-and-sandbox, --yolo). If base_path is a git repo → unified diff returned. If not → file list only (mtime detection). See Security & Limitations below before using.

Async debate (v0.3)

For long deliberation between 2-6 agents — round-robin, runs in the background, transcript persists to SQLite for replay.

When to use vs council

	council	debate_*
Latency	Sync, ~min wait	Async, runs minutes-to-hours
Stages	3 (independent → rank → synthesis)	N round-robin turns
Cancel	n/a	debate_cancel(id)
Persistence	Transcript in response	Auto-saved to ~/.consult-mcp/archive.db
Best for	Quick verdict with explicit ranking	Open-ended debate where agents react to each other

Quick example

// Start a debate; returns id immediately:
debate_start({
  "agents": ["claude", "codex", "gemini"],
  "topic": "Should we move our analytics from PostgreSQL to ClickHouse?",
  "max_turns": 10,
  "history_window": 6,
  "terminator": "any"
})
// → { "status": "success", "debate_id": "abc123...", "started_at": "..." }

// Poll progress (call as often as you like):
debate_status({ "debate_id": "abc123..." })
// → { "state": "running", "turn_count": 3, "transcript": [...] }

// When state == "completed":
// → { "state": "completed", "terminated_by": "done", "turn_count": 7, "transcript": [...] }

// Or cancel early:
debate_cancel({ "debate_id": "abc123..." })
// → { "already_finished": false, "requested_at": "..." }

// List debates (memory + archive):
debate_list({ "limit": 20 })

// Replay an old debate from SQLite:
debate_replay({ "debate_id": "abc123..." })

// Export as portable markdown (Obsidian-friendly frontmatter + transcript):
debate_export({ "debate_id": "abc123..." })
// → { "status": "success", "format": "md", "content": "---\nschema_version: 1\n..." }

// Or as stable JSON for programmatic consumers:
debate_export({ "debate_id": "abc123...", "format": "json" })
// → { "status": "success", "format": "json", "content": { "schema_version": 1, "turns": [...] } }

// Long transcripts: truncate per-turn bodies to fit MCP transport limits:
debate_export({ "debate_id": "abc123...", "truncate_body_chars": 2000 })

Export format

debate_export returns either markdown (default, copy-pasteable into Obsidian/Notion) or stable JSON. The JSON shape is versioned via schema_version: 1; future breaking changes bump the version. Markdown frontmatter is generated through yaml.safe_dump, so user-controlled fields (topic, agent_name, error_message) cannot break it through :, \n or ---. Total response size is capped at 5 MiB — pass truncate_body_chars=N to fit larger transcripts. All five debate states (pending, running, completed, cancelled, error) are exportable; running snapshots are explicitly marked.

Terminator semantics

The terminator controls soft early-stop (DONE marker emitted by the agent). Hard caps (max_turns, external cancel, all_slots_down) are unconditional.

Spec	Behavior
"any" (default)	OR(max_turns, done) — stops on either
"max_turns_only"	Ignore DONE; always run to max_turns
"done_only"	Stop only on DONE (still bounded by max_turns hard cap)
{"and": ["max_turns", "done"]}	Custom JSON expression

DONE detection is word-boundary aware: "abandoned" does NOT match, "...DONE" does.

Council — atomic 3-stage analysis

Single MCP call, ~min latency. Pattern from llm-council-mcp:

council({
  "agents": ["claude", "codex", "gemini"],
  "question": "Should we move analytics to ClickHouse?",
  "chairman": "claude"   // default = first agent
})
// → { "status": "success",
//     "stage1": [...],   // independent answers (parallel)
//     "stage2": [...],   // each agent ranks the anonymized responses
//     "stage3": { ... }, // chairman synthesizes
//     "stage2_parse_summary": { "json": 2, "fuzzy": 1, "unparseable": 0 } }

Stage 2 anonymizes responses as Response A, Response B, etc. so agents rank by content quality, not by author.

Niche tools (v0.4)

planner — structured task decomposition

planner({
  "agent": "claude",
  "problem": "Migrate the API from REST to gRPC, keeping the existing auth flow.",
  "depth": "tree"
})
// → { "status": "success", "agent": "claude",
//     "plan": {
//       "summary": "Phased migration, 8 tasks",
//       "tasks": [
//         {"id":"T1","title":"Define proto schema","depends_on":[],"estimated_size":"M"},
//         {"id":"T2","title":"Generate stubs","depends_on":["T1"],"estimated_size":"S"},
//         ...
//       ]
//     },
//     "depth": "tree" }

Pass depth="flat" to force depends_on=[] for every task. On JSON parse failure, the tool returns parse_error: true with raw_response preserved.

diff_review — git diff regression review

// With raw diff text:
diff_review({
  "agents": ["claude", "gemini"],
  "diff_text": "diff --git a/auth.py b/auth.py\n@@ ...",
  "focus": "security regressions"
})

// Or pulling from a git repo directly:
diff_review({
  "agents": ["claude"],
  "git_ref": "HEAD~3..HEAD",
  "cwd": "F:/repos/my-app"
})

Mutually exclusive: pass either diff_text (raw) OR git_ref + cwd. The reviewer persona is hardcoded.

apilookup — current-docs lookup

apilookup({
  "query": "Latest Anthropic Python SDK version + breaking changes vs 1.x"
})
// → { "agent": "gemini", "persona": "researcher_current",
//     "response": "As of 2026-04, the SDK is at 2.x ..." }

Default agent is gemini (web search built into the headless CLI). Other agents fall back to training-data answers and flag the staleness.

Personas

Eight built-in system prompts ship in v0.4:

Persona	Use case
default	Neutral helpful assistant
architect	Design, trade-offs, system structure
reviewer	Bugs, edge cases, security — returns severity-tagged JSON findings
researcher	Surveys alternatives, best practices, reference implementations
researcher_current	Same focus + emphasizes current docs / web sources / dates
coder	Minimal practical code, no over-engineering
skeptic	Anti-sycophancy — finds weaknesses, edge cases, counter-arguments
planner	Structured task decomposition — outputs JSON task tree

Adding your own

Create a markdown file at ~/.consult-mcp/personas/<name>.md:

---
name: security_reviewer
description: Focuses on auth, crypto, and OWASP top 10
---

You are a security-focused code reviewer. Concentrate on auth flaws,
crypto misuse, injection vectors, and OWASP top-10 risks. Skip generic
style feedback. Output severity-tagged findings as JSON.

It's available immediately after the next server restart: consult({"agent":"claude","prompt":"...","persona":"security_reviewer"}).

The full file format, length limits, naming policy and parser-error matrix are documented in Docs/persona-file-contract.md. User personas in ~/.consult-mcp/personas/ override built-ins on name collision — be explicit if that's what you want.

Community pack

A small curated set of ready-to-copy personas lives in examples/personas/community/ — currently security_reviewer, perf_reviewer, and regex_explainer. Pick what you want and cp it into ~/.consult-mcp/personas/. Names are guaranteed not to clash with built-ins. New PRs welcome — see the community README for contributing rules and the validator (python -m scripts.validate_personas examples/personas/community) that runs in CI.

Configuration

Built-in CLI configs live in the package (read-only). To override the command, args, or timeout for any agent — drop a JSON file at ~/.consult-mcp/agents/<name>.json matching the schema:

{
  "name": "claude",
  "command": ["claude"],
  "internal_args": ["--print", "--model", "opus"],
  "timeout_seconds": 180,
  "agent_class": "consult_mcp.agents.claude.ClaudeAgent"
}

User overrides replace the built-in entirely (no merging). Restart the MCP client to pick up changes.

Troubleshooting

Symptom	Likely cause	Fix
error.type: unknown_agent	CLI binary not in PATH	where claude (Windows) / which claude (Unix); install missing CLI
error.type: timeout	CLI took longer than 120s	pass timeout_seconds to the tool, or override timeout_seconds in ~/.consult-mcp/agents/<name>.json
error.type: cli_error with stderr "API key"	Missing OPENAI_API_KEY / GEMINI_API_KEY	set the env var (see API keys section)
error.type: cli_error with stderr "not logged in"	Claude Code not authenticated	run claude login once interactively
error.type: cli_error with stderr about model	Account/CLI version mismatch	upgrade the CLI: npm i -g @openai/codex@latest etc.
Server starts but no tools shown	Restart MCP client after install or .mcp.json edits	full restart (not just reload)
ImportError on Python 3.9	Python too old	python --version ≥ 3.10 required

⚠️ Security & Limitations

Read-only by default. consult, consult_parallel, codereview, consensus, and challenge invoke CLIs without mutation/sandbox-bypass flags. Agents return text answers; they do not edit files or execute commands.

implement is the only mutation-capable tool (v0.2). It activates --permission-mode acceptEdits (Claude), --dangerously-bypass-approvals-and-sandbox (Codex), and --yolo (Gemini). A malicious or careless prompt can delete files, exfiltrate secrets, or run arbitrary commands. Run implement in isolated repositories and code-review the resulting diff before trusting it. Mutation flags are kept in a separate mutation_args field per agent config and only applied when implement is called — they cannot leak into other tools.

Local-only. consult-mcp runs as a single process on a single machine. No cross-machine coordination, no daemon, no shared state.

Privacy. Prompts and responses pass through whichever LLM provider you've configured per CLI (Anthropic, OpenAI, Google). Don't send data you wouldn't paste into the respective web UIs. The persona system prompt is appended to every request.

Restart loss. Active debates (state in {pending, running}) live only in memory. Restarting the MCP client kills any in-flight debate — the asyncio task is gone, no resume, the transcript up to that point is NOT archived (archive only writes on terminal state). Completed debates are persisted to ~/.consult-mcp/archive.db and replayable via debate_replay.

Resource limits. debate_start rejects new starts when ≥ 5 debates are already active (override via CONSULT_MCP_MAX_ACTIVE_DEBATES env). This is a guard against accidental fork-bomb when multiple chained tool calls trigger debate creation.

Privacy of archive. ~/.consult-mcp/archive.db is plain SQLite, not encrypted. Anyone with file-system access can read transcripts. Don't run debates on data you wouldn't write to a plain file.

Roadmap

Iteration	Focus	Status
IT-001	MVP — consult, consult_parallel, 5 personas	✅ shipped (v0.1)
IT-002	Specialized — codereview, consensus, challenge, implement	✅ shipped (v0.2)
IT-003	Async debate — debate_*, council, SQLite archive	✅ shipped (v0.3)
IT-004	Niche — planner, diff_review, apilookup	✅ shipped (v0.4)
IT-006	Markdown export — debate_export	✅ shipped (v0.6)
IT-007	Community personas pack + persona-file contract + validator	✅ shipped (v0.7)
IT-008	Streaming — debate_run, council progress + cancellation	✅ shipped (v0.8)
IT-010	Composite — delegate_implementation (plan→implement→review)	✅ this release (v0.10)

What's next

• Streaming progress notifications for async debates (MCP SSE)
• Web UI / dashboard for archived debate replay
• Community personas (PRs welcome)
• Documentation site (Sphinx/MkDocs) once tool count > 15 or README > 800 lines

Detailed iteration plans live in Docs/plans/iterations/.

License

MIT — see LICENSE.