mcp-deep-research

Stdio MCP server that exposes Gemini Deep Research as a read-only tool to MCP clients (opencode, Claude Code, Codex CLI). Designed as one strengthening input to the @researcher methodology in agentic_workspace — not a replacement for source classification, claim ratings, or counter-research.

Capabilities

One MVP tool: deep_research.run.

Field	Type	Required	Notes
question	string	yes	Min length 8 chars.
context	string	no	Background prepended to the prompt.
mode	"standard" / "max"	no	Picks the Deep Research agent variant. Default standard.
source_requirements	string	no	Free-text constraints (e.g. "primary sources only").
counter_research	bool	no	Default true. Asks model to surface dissenting positions.
max_runtime_seconds	int	no	Default 600, capped at 1800.

Output shape: report (Markdown) + summary + claims[] + sources[] + counter_research[] + api_metadata{}.

MVP honesty note — report is the authoritative payload. In live mode against Gemini's API, claims[] and counter_research[] are placeholder shapes (Claim(statement="(see report)", ...)); the live adapter does not post-process Deep Research's prose into structured claims. sources[] is populated best-effort from URL annotations in the response, with source_class defaulting to "unknown" — consumers should classify sources themselves.

The MCP feeds raw evidence; methodology (claim ratings, source classification, counter-research) lives in the consuming agent (e.g. @researcher in agentic_workspace). In stub mode the structured fields contain synthetic-but-shape-compatible content for development and testing — also not authoritative as evidence.

Modes

Env var	Effect
MCP_DEEP_RESEARCH_STUB=1	Stub mode — deterministic synthetic response. No network, no key required. Default for tests.
MCP_DEEP_RESEARCH_STUB unset + GEMINI_API_KEY set	Live mode — starts a background Deep Research interaction and polls until completion.
MCP_DEEP_RESEARCH_STUB unset + MCP_DEEP_RESEARCH_OP_REF set	Live mode resolves the key via op read on the tool call, not at server startup.
MCP_DEEP_RESEARCH_STUB unset + key missing	Live-mode call fails with an actionable error.
MCP_DEEP_RESEARCH_DEBUG=1	Logs prompt/report at DEBUG. Off by default — metadata only.

Run

# Stub mode (no key)
MCP_DEEP_RESEARCH_STUB=1 uv run --project . mcp-deep-research

# Live mode (key resolved by wrapper)
~/.local/bin/mcp-deep-research

Wrapper

~/.local/bin/mcp-deep-research exports the 1Password item reference and execs the server. The server resolves the key via op read on live tool calls so MCP clients can list tools without a credential prompt. Never put the key inline in MCP config.

In opencode, the tool is exposed with the server prefix as deep_research_deep_research_run.

Tests

uv run --project . --extra dev pytest

See also

• agentic_workspace handbook entry
• ADR-0007 — multi-agent orchestration strategy