Deep Research MCP

A Python-based agent that integrates research providers with Claude Code through the Model Context Protocol (MCP). It supports both OpenAI (Responses API with web search and code interpreter) and the open-source Open Deep Research stack (based on smolagents).

Prerequisites

• Python 3.9+
• One of:
  • OpenAI API access (Responses API models, e.g., o4-mini-deep-research-2025-06-26)
  • Open Deep Research dependencies (installed via requirements.txt)
• Claude Code, or any other assistant supporting MCP integration

Configuration

Configuration File

Create a ~/.deep_research file in your home directory using TOML format.

Common settings:

[research]                                  # Core Deep Research functionality
provider = "openai"                         # Available options: "openai", "open-deep-research" -- defaults to "openai"
model = "o4-mini-deep-research-2025-06-26"  # OpenAI: model identifier; ODR: LiteLLM model identifier, e.g., openai/qwen/qwen3-coder-30b
api_key = "sk-your-api-key"                 # API key, optional
base_url = "https://api.openai.com/v1"      # OpenAI: OpenAI-compatible endpoint; ODR: LiteLLM-compatible endpoint, e.g., http://localhost:1234/v1

# Task behavior
timeout = 1800
poll_interval = 30
max_retries = 3

# Largely based on https://cookbook.openai.com/examples/deep_research_api/introduction_to_deep_research_api_agents
[clarification]                                       # Optional query clarification component
enable = true
triage_model = "gpt-5-mini"
clarifier_model = "gpt-5-mini"
instruction_builder_model = "gpt-5-mini"
api_key = "sk-your-api-key"             # Optional, overrides api_key
base_url = "https://api.openai.com/v1"  # Optional, overrides base_url

[logging]
level = "INFO"

OpenAI provider example:

[research]
provider = "openai"
model = "o4-mini-deep-research-2025-06-26"  # OpenAI model
api_key = "sk-..."                          # Defaults to OPENAI_API_KEY
base_url = "https://api.openai.com/v1"      # OpenAI-compatible endpoint
timeout = 1800
poll_interval = 30
max_retries = 3

Perplexity (via Sonar Deep Research and Perplexity's OpenAI-compatible endpoint) provider example:

[research]
provider = "openai"
model = "sonar-deep-research"               # Perplexity's Sonar Deep Research
api_key = "ppl-..."                         # Defaults to OPENAI_API_KEY
base_url = "https://api.perplexity.ai"      # Perplexity's OpenAI-compatible endpoint
timeout = 1800
poll_interval = 30
max_retries = 3

Open Deep Research provider example:

[research]
provider = "open-deep-research"
model = "openai/qwen/qwen3-coder-30b"  # LiteLLM-compatible model id
base_url = "http://localhost:1234/v1"  # LiteLLM-compatible endpoint (local or remote)
api_key = ""                           # Optional if endpoint requires it
timeout = 1800

Optional env variables for Open Deep Research tools:

• SERPAPI_API_KEY or SERPER_API_KEY: enable Google-style search
• HF_TOKEN: optional, logs into Hugging Face Hub for gated models

Claude Code Integration

1. Configure MCP Server

Add the MCP server using Claude Code's command line:

claude mcp add deep-research python /path/to/deep-research-mcp/src/deep_research_mcp/mcp_server.py

Replace /path/to/deep-research-mcp/ with the actual path to your cloned repository.

HTTP transport: If your client supports MCP-over-HTTP, you can run this server in HTTP streaming mode (see "As an MCP Server" below) and configure the client to connect to http://127.0.0.1:8080/. Refer to your client's documentation for how to add an HTTP MCP server.

For multi-hour research, raise Claude Code's tool timeout before launching the CLI and rely on incremental status polls:

export MCP_TOOL_TIMEOUT=14400000  # 4 hours
claude --mcp-config ./.mcp.json

Kick off work with deep_research or research_with_context, note the returned job ID, and call research_status to stream progress without letting any single tool call stagnate.

1. Use in Claude Code:
   • The research tools will appear in Claude Code's tool palette
   • Simply ask Claude to "research [your topic]" and it will use the Deep Research agent
   • For clarified research, ask Claude to "research [topic] with clarification" to get follow-up questions

OpenAI Codex Integration

1. Configure MCP Server

Add the MCP server configuration to your ~/.codex/config.toml file:

[mcp_servers.deep-research]
command = "python"
args = ["/path/to/deep-research-mcp/src/deep_research_mcp/mcp_server.py"]
startup_timeout_ms = 30000  # 30 seconds for server startup
request_timeout_ms = 7200000  # 2 hours for long-running research tasks
# Alternatively, set tool_timeout_sec when using newer Codex clients
# tool_timeout_sec = 14400.0     # 4 hours for deep research runs

Replace /path/to/deep-research-mcp/ with the actual path to your cloned repository.

Important timeout configuration:

• startup_timeout_ms: Time allowed for the MCP server to start (default: 30000ms / 30 seconds)
• request_timeout_ms: Maximum time for research queries to complete (recommended: 7200000ms / 2 hours for comprehensive research)
• tool_timeout_sec: Preferred for newer Codex clients; set this to a large value (e.g., 14400.0 for 4 hours) when you expect long-running research.
• Kick off research once to capture the job ID, then poll research_status so each tool call remains short and avoids hitting client timeouts.

Without proper timeout configuration, long-running research queries may fail with "request timed out" errors.

Some environments also support MCP-over-HTTP. If available, run the server in HTTP mode and configure the client with the base URL (for example, http://127.0.0.1:8080/). Consult the specific client's docs for setup steps.

1. Use in OpenAI Codex:
   • The research tools will be available automatically when you start Codex
   • Ask Codex to "research [your topic]" and it will use the Deep Research MCP server
   • For clarified research, ask for "research [topic] with clarification"

Gemini CLI Integration

1. Configure MCP Server

Add the MCP server using Gemini CLI's built-in command:

gemini mcp add deep-research python /path/to/deep-research-mcp/src/deep_research_mcp/mcp_server.py

Or manually add to your ~/.gemini/settings.json file:

{
  "mcpServers": {
    "deep-research": {
      "command": "python",
      "args": ["/path/to/deep-research-mcp/src/deep_research_mcp/mcp_server.py"],
      "env": {
        "OPENAI_API_KEY": "$OPENAI_API_KEY"
      }
    }
  }
}

Replace /path/to/deep-research-mcp/ with the actual path to your cloned repository.

1. Use in Gemini CLI:
   • Start Gemini CLI with gemini
   • The research tools will be available automatically

• Ask Gemini to "research [your topic]" and it will use the Deep Research MCP server
• Use /mcp command to view server status and available tools

HTTP transport: If your Gemini environment supports MCP-over-HTTP, you may run the server with --transport http and configure Gemini with the server URL.

Usage

As a Standalone Python Module

import asyncio
from deep_research_mcp.agent import DeepResearchAgent
from deep_research_mcp.config import ResearchConfig

async def main():
    # Initialize configuration
    config = ResearchConfig.from_env()
    
    # Create agent
    agent = DeepResearchAgent(config)
    
    # Perform research
    result = await agent.research(
        query="What are the latest advances in quantum computing?",
        system_prompt="Focus on practical applications and recent breakthroughs"
    )
    
    # Print results
    print(f"Report: {result['final_report']}")
    print(f"Citations: {result['citations']}")
    print(f"Research steps: {result['reasoning_steps']}")

# Run the research
asyncio.run(main())

As an MCP Server

Two transports are supported: stdio (default) and HTTP streaming.

# 1) stdio (default) — for editors/CLIs that spawn a local process
python src/deep_research_mcp/mcp_server.py

# 2) HTTP streaming — start a local HTTP MCP server
python src/deep_research_mcp/mcp_server.py --transport http --host 127.0.0.1 --port 8080

Notes:

• HTTP mode uses streaming responses provided by FastMCP. The tools in this server return their full results when a research task completes; streaming is still beneficial for compatible clients and for future incremental outputs.
• To use HTTP mode, point your MCP-over-HTTP client at the host/port you chose.

Example Queries

# Basic research query
result = await agent.research("Explain the transformer architecture in AI")

# Research with code analysis
result = await agent.research(
    query="Analyze global temperature trends over the last 50 years",
    include_code_interpreter=True
)

# Custom system instructions
result = await agent.research(
    query="Review the safety considerations for AGI development",
    system_prompt="""
    Provide a balanced analysis including:
    - Technical challenges
    - Current safety research
    - Regulatory approaches
    - Industry perspectives
    Include specific examples and data where available.
    """
)

# With clarification (requires ENABLE_CLARIFICATION=true)
clarification_result = agent.start_clarification("quantum computing applications")
if clarification_result.get("needs_clarification"):
    # Answer questions programmatically or present to user
    answers = ["Hardware applications", "Last 5 years", "Commercial products"]
    agent.add_clarification_answers(clarification_result["session_id"], answers)
    enriched_query = agent.get_enriched_query(clarification_result["session_id"])
    result = await agent.research(enriched_query)

Clarification Features

The agent includes an optional clarification system to improve research quality through follow-up questions.

Configuration

Enable clarification in your ~/.deep_research file:

[clarification]
enable_clarification = true
triage_model = "gpt-5-mini"                                    # Optional, defaults to gpt-5-mini
clarifier_model = "gpt-5-mini"                                 # Optional, defaults to gpt-5-mini
instruction_builder_model = "gpt-5-mini"                       # Optional, defaults to gpt-5-mini
clarification_api_key = "sk-your-clarification-api-key-here"   # Optional custom API key for clarification models
clarification_base_url = "https://custom-api.example.com/v1"   # Optional custom endpoint for clarification models

Usage Flow

1. Start Clarification:

   result = agent.start_clarification("your research query")

2. Check if Questions are Needed:

   if result.get("needs_clarification"):
       questions = result["questions"]
       session_id = result["session_id"]

3. Provide Answers:

   answers = ["answer1", "answer2", "answer3"]
   agent.add_clarification_answers(session_id, answers)

4. Get Enriched Query:

   enriched_query = agent.get_enriched_query(session_id)
   final_result = await agent.research(enriched_query)

Integration with AI Assistants

When using with AI Assistants via MCP tools:

1. Request Clarification: Use deep_research() with request_clarification=True
2. Answer Questions: The AI Assistant will present questions to you
3. Deep Research: The AI Asssitant will automatically use research_with_context() with your answers

API Reference

DeepResearchAgent

The main class for performing research operations.

Methods

• research(query, system_prompt=None, include_code_interpreter=True, callback_url=None)

  • Performs deep research on a query
  • Returns: Dictionary with final report, citations, and metadata

• get_task_status(task_id)

  • Check the status of a research task
  • Returns: Task status information

• start_clarification(query)

  • Analyze query and generate clarifying questions if needed
  • Returns: Dictionary with questions and session ID

• add_clarification_answers(session_id, answers)

  • Add answers to clarification questions
  • Returns: Session status information

• get_enriched_query(session_id)

  • Generate enriched query from clarification session
  • Returns: Enhanced query string

ResearchConfig

Configuration class for the research agent.

Parameters

• provider: Research provider (openai or open-deep-research; default: openai)
• model: Model identifier
  • OpenAI: Responses model (e.g., gpt-5-mini)
  • Open Deep Research: LiteLLM model id (e.g., openai/qwen/qwen3-coder-30b)
• api_key: API key for the configured endpoint (optional). Defaults to env OPENAI_API_KEY.
• base_url: OpenAI-compatible API base URL (optional). Defaults to env OPENAI_BASE_URL.
• timeout: Maximum time for research in seconds (default: 1800)
• poll_interval: Polling interval in seconds (default: 30)
• max_retries: Maximum retry attempts (default: 3)
• enable_clarification: Enable clarifying questions (default: False)
• triage_model: Model for query analysis (default: gpt-5-mini)
• clarifier_model: Model for query enrichment (default: gpt-5-mini)
• clarification_api_key: Custom API key for clarification models (optional, defaults to api_key)
• clarification_base_url: Custom OpenAI-compatible endpoint for clarification models (optional, defaults to base_url)

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=deep-research-mcp tests/

# Run specific test file
pytest tests/test_agent.py