/deep-research-mcp

name: deep-research-mcp
description: Use this guide only for the `deep-research-mcp` repository/project when you need to run, integrate, or debug its CLI, Python API, or MCP server. It covers direct agent execution, named-backend selection, OpenAI Responses with GPT-6 Sol, experimental Codex subscription access, Gemini Deep Research, Tavily Research, DR-Tulu, self-hosted Gnosis search, task recovery, and HTTP or stdio MCP usage. Do not use it for Deep Research systems in general, for unrelated MCP servers, or for the Textual TUI.

Deep Research MCP

This document is specifically about the `deep-research-mcp` project/repository, not Deep Research systems in general.

Repository: `https://github.com/pminervini/deep-research-mcp`

Use When

• You are working in or against the `deep-research-mcp` repository/project.
• You need to run `deep-research-cli` in direct agent mode.
• You need to call `DeepResearchAgent` and `ResearchConfig` from Python.
• You need to expose the `deep-research-mcp` project as an MCP server with `deep-research-mcp`.
• You need to connect to the MCP server from another client over HTTP.
• You need to understand which backend is used for OpenAI, Codex subscription access, Gemini, Tavily, DR-Tulu, or Gnosis.
• You need to troubleshoot provider mix-ups caused by values already stored in `~/.deep_research`.

Do Not Use When

• You only need the Textual TUI in `cli/deep-research-tui.py`.
• You need a generic guide to Deep Research agents, generic research workflows, or MCP outside the `deep-research-mcp` codebase.
• You are looking for model-selection advice outside the providers this repository already implements.

Mental Model

There are three layers:

1. `deep-research-cli` is the installed user-facing CLI. 2. `src/deep_research_mcp/agent.py` orchestrates research, callbacks, and status checks. 3. `src/deep_research_mcp/backends/*.py` performs provider-specific work.

The CLI can run in two modes:

• Agent mode: instantiate `DeepResearchAgent` directly.
• MCP client mode: connect to a running HTTP MCP server with `--server-url`.

The MCP server entrypoint is the console script:

uv run deep-research-mcp

It exposes three tools:

• `deep_research`
• `research_status`
• `list_backends`

Setup

The commands below assume you are running from the repository root.

Recommended install

uv sync --upgrade --extra dev

Compatible editable install

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

Environment variables by provider

OpenAI:

export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

Gemini:

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

DR-Tulu:

• there is no single required key defined by `deep-research-mcp` itself
• you must have a running DR-Tulu service that exposes `POST {base_url}/chat`

Provider Matrix

| Provider | Backend module | How research is executed | Status polling | Notes | | --- | --- | --- | --- | --- | | `openai` + `api_style=responses` | `openai_backend.py` | OpenAI Responses API in background mode with GPT-6 Sol, `web_search`, and optionally `code_interpreter` | Yes, with report recovery | Default deep-research path | | `openai` + `api_style=chat_completions` | `openai_backend.py` | One-shot Chat Completions call | No persistent status | Useful for OpenAI-compatible providers like Perplexity, Groq, Ollama, vLLM | | `openai-codex` | `codex_backend.py` | Synchronous Responses SSE stream with native web search | No | Experimental subscription OAuth route; no Code Interpreter or report recovery | | `gemini` | `gemini_backend.py` | Gemini Interactions API with `background=True` | Yes, with report recovery | Uses `google-genai`; `include_analysis` is ignored by the backend | | `tavily` | `tavily_backend.py` | Asynchronous Tavily Research API | Yes, with report recovery | Models `mini` (default), `pro`, or `auto`; uses `TAVILY_API_KEY` | | `dr-tulu` | `dr_tulu_backend.py` | `POST {base_url}/chat` | No | Requires a separately running DR-Tulu service | | `gnosis` | `gnosis_backend.py` | openJiuwen `POST /runs` plus shared output files | Completed-answer recovery; live task liveness unavailable | Requires native request-options JSON and shared output mount; no Code Interpreter |

Config Precedence And The Most Important Pitfall

For the default backend, `ResearchConfig.load()` merges:

1. Built-in defaults 2. `~/.deep_research` 3. Environment variables 4. CLI flags, which the CLI layers into an environment mapping without changing `os.environ`

This matters because the TOML file is flattened into keys like `RESEARCH_API_KEY` and `RESEARCH_BASE_URL`. If your saved config is pinned to Gemini and you run:

uv run deep-research-cli --provider openai research "..."

you may still send the request to Gemini or send the Gemini key to OpenAI unless you also override:

• `--api-key`
• `--base-url`
• sometimes `--model`

Safe pattern when switching providers from the command line:

uv run deep-research-cli \
  --provider openai \
  --api-style responses \
  --model gpt-6-sol \
  --api-key "$OPENAI_API_KEY" \
  --base-url https://api.openai.com/v1 \
  research "..."

For repeated provider switching, prefer named backends to manual overrides. See [Configuration in README](../../README.md#configuration) for canonical TOML examples and environment-key mappings.

Named backend selection

`[research]` defines the `default` backend. Each `[backends.<name>]` table requires `provider`; `default` is reserved and names cannot contain `:`.

• Named tables do not inherit provider, model, API style, credentials, endpoint,

or reasoning effort from `[research]` or provider-scoped `RESEARCH_*` settings.

• If a named table omits its key or endpoint, provider-specific environment

variables and defaults apply. Explicit table values win over those aliases.

• Runtime settings are inherited unless the table overrides them.