learningcircuit--local-deep-research/docs/mcp-server.md

MCP Server Guide

LDR provides an MCP (Model Context Protocol) server that exposes its research capabilities to AI assistants like Claude Desktop, Claude Code, and OpenClaw. MCP is an open protocol by Anthropic that lets AI applications call external tools over a standardized interface.

The MCP server exposes 8 research tools — 5 research tools and 3 discovery tools — over STDIO transport only (local use, no network exposure). MCP support is an optional dependency that must be installed separately.

Quick Start

Installation

pip install "local-deep-research[mcp]"

Claude Desktop Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "local-deep-research": {
      "command": "ldr-mcp",
      "env": {
        "LDR_LLM_PROVIDER": "openai",
        "LDR_LLM_OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Code Configuration

Add to your .mcp.json (project-level) or ~/.claude/mcp.json (global):

{
  "mcpServers": {
    "local-deep-research": {
      "command": "ldr-mcp",
      "env": {
        "LDR_LLM_PROVIDER": "ollama",
        "LDR_LLM_OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

OpenClaw Configuration

Add LDR as a skill in your openclaw.json:

{
  "mcpServers": {
    "local-deep-research": {
      "command": "ldr-mcp",
      "env": {
        "LDR_LLM_PROVIDER": "openai",
        "LDR_LLM_OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

The configuration format is the same as Claude Desktop. See the OpenClaw MCP documentation for details on skill registration.

Verify Installation

Run ldr-mcp in a terminal. It should start and wait for STDIO input (no output means it's working). Press Ctrl+C to stop.

First Research

Open Claude Desktop and try:

Use quick_research to find information about quantum computing applications

Configuration

The MCP server uses the same settings system as the main LDR application. There are no dedicated MCP-specific environment variables. All configuration is done through standard LDR_* environment variables, set in the Claude Desktop config's env block.

Environment Variables

LLM Settings:

Variable	Description	Example
LDR_LLM_PROVIDER	LLM provider	openai, ollama, anthropic
LDR_LLM_MODEL	Model name	gpt-4, llama3:8b, claude-sonnet-4-20250514
LDR_LLM_OPENAI_API_KEY	OpenAI API key	sk-...
LDR_LLM_TEMPERATURE	Generation temperature	0.7

Search Settings:

Variable	Description	Example
LDR_SEARCH_TOOL	Default search engine	searxng, arxiv, wikipedia
LDR_SEARCH_SEARCH_STRATEGY	Default strategy	source-based, focused-iteration
LDR_SEARCH_ITERATIONS	Default iteration count	2
LDR_SEARCH_QUESTIONS_PER_ITERATION	Questions per iteration	3

Note: The strategy variable uses a double underscore (SEARCH_SEARCH_STRATEGY) because the settings key is search.search_strategy.

Optional Search API Keys:

Variable	Description
LDR_TAVILY_API_KEY	Tavily search API key
LDR_BRAVE_SEARCH_API_KEY	Brave Search API key
LDR_SERPAPI_API_KEY	SerpAPI key

Example Configurations

OpenAI (default):

{
  "mcpServers": {
    "local-deep-research": {
      "command": "ldr-mcp",
      "env": {
        "LDR_LLM_PROVIDER": "openai",
        "LDR_LLM_MODEL": "gpt-4",
        "LDR_LLM_OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Ollama (fully local, no API key needed):

{
  "mcpServers": {
    "local-deep-research": {
      "command": "ldr-mcp",
      "env": {
        "LDR_LLM_PROVIDER": "ollama",
        "LDR_LLM_MODEL": "llama3:8b"
      }
    }
  }
}

Anthropic:

{
  "mcpServers": {
    "local-deep-research": {
      "command": "ldr-mcp",
      "env": {
        "LDR_LLM_PROVIDER": "anthropic",
        "LDR_LLM_MODEL": "claude-sonnet-4-20250514",
        "LDR_LLM_ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Logging

All log output goes to stderr (stdout is reserved for the JSON-RPC protocol). The log level is hardcoded to INFO — there is no environment variable to change it.

Available Tools

Research Tools

quick_research

Fast research summary. Typically takes 1-5 minutes.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Research question (max 10,000 chars)
search_engine	string	No	Search engine to use (e.g., "searxng", "arxiv", "wikipedia")
strategy	string	No	Research strategy (e.g., "source-based", "focused-iteration")
iterations	integer	No	Number of search iterations (1-10)
questions_per_iteration	integer	No	Questions per iteration (1-10)

Returns:

{
  "status": "success",
  "summary": "Research summary text...",
  "findings": ["finding1", "finding2"],
  "sources": ["https://example.com/source1"],
  "iterations": 3,
  "formatted_findings": "Formatted markdown findings..."
}

Best for: fast fact-checking, simple queries, getting a quick overview.

---

detailed_research

Comprehensive research analysis. Typically takes 5-15 minutes.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Research question (max 10,000 chars)
search_engine	string	No	Search engine to use
strategy	string	No	Research strategy
iterations	integer	No	Number of search iterations (1-20)
questions_per_iteration	integer	No	Questions per iteration (1-10)

Returns:

{
  "status": "success",
  "query": "original query",
  "research_id": "unique-id",
  "summary": "Detailed summary...",
  "findings": ["finding1", "finding2"],
  "sources": ["https://example.com/source1"],
  "iterations": 5,
  "formatted_findings": "Formatted markdown findings...",
  "metadata": {"timestamp": "...", "search_tool": "...", "strategy": "..."}
}

Best for: in-depth analysis, nuanced topics, comprehensive coverage.

---

generate_report

Full structured markdown report with sections, citations, and bibliography. Typically takes 10-30 minutes.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Research topic (max 10,000 chars)
search_engine	string	No	Search engine to use
searches_per_section	integer	No	Searches per report section (1-10, default 2)

Returns:

{
  "status": "success",
  "content": "# Report Title\n\n## Section 1\n...",
  "metadata": {"timestamp": "...", "query": "..."}
}

Best for: publication-quality structured reports with proper citations.

---

analyze_documents

Search and analyze documents in a local collection using RAG. Typically takes 30 seconds - 2 minutes.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search query (max 10,000 chars)
collection_name	string	Yes	Engine ID of the collection (e.g., "collection_3"). Use list_search_engines() to find available collections.
max_results	integer	No	Maximum documents to retrieve (1-100, default 10)

Returns:

{
  "status": "success",
  "summary": "Summary of findings from documents...",
  "documents": [{"content": "...", "metadata": {"source": "file.pdf", "page": 1}}],
  "collection": "my-papers",
  "document_count": 5
}

The data flow is: collection_name → FAISS index lookup → semantic similarity search → LLM summarization.

Best for: searching uploaded PDFs and documents in local collections. Use list_search_engines() to discover available collection IDs.

---

search

Raw search results without LLM processing. Typically takes 5-30 seconds. No LLM cost.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search query (max 10,000 chars)
engine	string	Yes	Search engine to use (e.g., "arxiv", "wikipedia", "searxng"). Use list_search_engines() to see options.
max_results	integer	No	Maximum results to return (1-100, default 10)

Returns:

{
  "status": "success",
  "query": "quantum computing",
  "engine": "arxiv",
  "result_count": 10,
  "results": [
    {
      "title": "Quantum Computing: An Overview",
      "link": "https://arxiv.org/abs/2301.12345",
      "snippet": "We present a comprehensive overview..."
    }
  ]
}

Common engines: arxiv (academic papers), pubmed (medical literature), wikipedia (encyclopedic), searxng (meta-search), github (code/repos), semantic_scholar (citations). Use list_search_engines() for the full list.

Best for: raw search results for your own analysis, quick lookups, checking what sources are available before running full research. Especially useful for monitoring and subscriptions — check for new content regularly without LLM cost.

Discovery Tools

These tools return instantly and are useful for exploring available options.

list_search_engines

Returns available search engines with their descriptions, strengths, weaknesses, and whether they require an API key or run locally.

list_strategies

Returns available research strategies with their names and descriptions.

get_configuration

Returns the current server configuration including LLM provider, model, temperature, and search defaults. API keys are intentionally excluded from the response.

Research Strategies Guide

LDR supports the following research strategies via MCP:

Strategy	Speed	Accuracy	Best For
source-based	Medium	High	Topics needing authoritative citations
focused-iteration	Medium	Highest (~95%)	Complex factual / technical topics
focused-iteration-standard	Medium	High	Comprehensive long-form answers with citations
topic-organization	Medium	High	Structured output clustered by theme
langgraph-agent	Varies	High	Autonomous agentic research across engines

Use list_strategies() to see all available strategies and their descriptions.

Error Handling

All tool calls return structured error responses when something goes wrong. Errors are classified into these categories:

Error Type	Cause	User-Facing Message
validation_error	Bad parameters (empty query, out-of-range values)	Specific message (e.g., "Query cannot be empty")
auth_error	Invalid or missing API key (401)	"...failed (auth_error). Check server logs."
service_unavailable	Provider or search engine down (503)	"...failed (service_unavailable). Check server logs."
timeout	Operation took too long	"...failed (timeout). Check server logs."
rate_limit	API quota exceeded (429)	"...failed (rate_limit). Check server logs."
connection_error	Network connectivity issue	"...failed (connection_error). Check server logs."
model_not_found	Model doesn't exist (404)	"...failed (model_not_found). Check server logs."
unknown	Unclassified error	"...failed (unknown). Check server logs."

All errors are logged to stderr with full detail. User-facing messages are sanitized — no stack traces or API keys are exposed.

Security Model

• STDIO-only transport — The server runs mcp.run(transport="stdio"), which cannot be accessed over a network. Only the parent process (e.g., Claude Desktop, Claude Code, OpenClaw) can communicate with it.
• No authentication needed — OS-level process isolation provides security. The parent process controls access.
• API keys never returned — get_configuration intentionally excludes API keys from its response.
• Error messages sanitized — No internal details, stack traces, or credentials in error responses.
• Input validation — All parameters have strict bounds and type checking.
• Per-call settings overrides — Settings overrides from tool parameters are in-memory only and not persisted.
• @no_db_settings — Prevents database settings access from MCP calls.

Security Note: This MCP server is designed for local use only. Do not expose it over a network without implementing proper security controls (OAuth, rate limiting). See the MCP Security Guide for network deployment requirements.

Docker Deployment

The MCP server uses STDIO transport, which requires direct process communication with the host AI assistant (e.g., Claude Desktop). This means it must run on the host machine, not inside a Docker container.

• MCP server (ldr-mcp) — install and run on the host machine only
• Web service (ldr-web) — can run in Docker

The Docker image does not include MCP extras, and adding them would not help — the STDIO transport cannot bridge the container boundary to reach Claude Desktop.

Usage Examples

Prompt Patterns

Quick fact-checking:

Use quick_research to find: What is the current population of Tokyo?

Deep analysis:

Use detailed_research with focused-iteration strategy to analyze:
What are the latest advances in solid-state battery technology?

Full report:

Generate a report on the impact of AI on drug discovery using source-based strategy

Document search:

Search collection 'research-papers' for: machine learning optimization techniques

Agentic research:

Use the langgraph-agent strategy to research the environmental impact of cryptocurrency mining,
considering both proof-of-work and proof-of-stake systems

Individual search engines (no LLM cost, fast):

Search arxiv for recent papers on diffusion models
Search pubmed for CRISPR clinical trials 2024
Search wikipedia for quantum error correction
Search github for agentic research frameworks

The search tool is especially useful for monitoring and subscriptions — check for new content on a topic regularly without burning LLM tokens. An AI agent can call search to get raw results, then decide whether to run a full detailed_research only when something interesting appears.

Tips

• Use search for fast, free lookups before committing to a full research run
• Start with quick_research to test your setup, then upgrade to detailed_research for depth
• Use focused-iteration strategy for highest accuracy on technical topics
• Lower temperature (0.3-0.5) for factual research, higher (0.8-1.2) for creative exploration (valid range: 0.0-2.0)
• Call list_search_engines and list_strategies first to see what's available in your configuration
• Use get_configuration to verify your LLM and search settings are correct

Troubleshooting

Problem	Solution
Server won't start	Verify MCP extras are installed: pip install "local-deep-research[mcp]"
"API key" errors	Check env vars in your Claude Desktop config (e.g., LDR_LLM_OPENAI_API_KEY)
"Invalid strategy" error	Run list_strategies() to see valid strategy names
"Unknown search engine" error	Run list_search_engines() to see available engines
No results returned	Try a different search_engine or make your query more specific
Server logs	Check stderr output. Log level is hardcoded to INFO.

Related Documentation

• API Quickstart — HTTP and Python API access
• Search Engines Guide — Available search engines and configuration
• Configuration Reference — All LDR settings
• Features Overview — All LDR features
• CLI Tools — Command-line tools including ldr-mcp