Gigaxity Deep Research

Gigaxity Deep Research — Open-source deep research MCP server for Claude Code, Codex, Cursor, Hermes, and any MCP-capable agent

Open-source deep research MCP server for Claude Code, Hermes, Cursor, and any MCP-compatible agent. Qwen3-30B-A3B-Thinking via OpenRouter plus multi-source web synthesis with citations.

Gigaxity Deep Research is a multi-source synthesis pipeline — six MCP tools (two primitives search/research plus four deep-research tools ask/discover/synthesize/reason) with a matching FastAPI REST surface, fronting parallel multi-source search, RRF fusion, citation binding, and contradiction detection. The synthesis stage runs against any OpenAI-compatible chat-completions model; the recommended default is Alibaba's Qwen3-30B-A3B-Thinking, a reasoning-tuned 30B-A3B MoE model, but DeepSeek-R1, Qwen-QwQ, Llama 3.x, and hosted-aggregator endpoints (OpenRouter and the like) all work — pick any model your endpoint serves. The search layer pulls from a "Triple Stack" of complementary MCPs (Context7, Exa, Jina) alongside SearXNG, Tavily, and LinkUp connectors. A bundled gptr-mcp companion — the MCP shim around GPT Researcher — adds Reddit, X, and YouTube as social-first sources.

If you want to run the synthesis model on your own hardware, the local-inference branch swaps OpenRouter for any OpenAI-compatible endpoint (vLLM, SGLang, or llama.cpp). The search-MCP layer is priced separately by each provider. See [docs/guides/free-tier-strategy.md](docs/guides/free-tier-strategy.md) for what their free tiers cover and how to wire them up.

Python on FastAPI. MIT License. Runs as an MCP stdio server, FastAPI REST API, or both. Drop-in instructions for the full deep research stack live in [CLAUDE.md](CLAUDE.md) / [AGENTS.md](AGENTS.md) (byte-identical) so any MCP-capable harness — Claude Code, Codex, Cursor, Hermes, etc. — or a standalone agent (system-prompt path) can mirror the configuration.

[](LICENSE) [](pyproject.toml) [](https://modelcontextprotocol.io/)

---

What it does

Gigaxity Deep Research wires a multi-source search layer (SearXNG, Tavily, LinkUp) to an RRF fusion stage and a synthesis engine with citation binding, then exposes the whole pipeline as six MCP tools — two primitives (search, research) plus four deep-research tools (ask, discover, synthesize, reason) — that Claude Code or any MCP-compatible agent can call. The synthesis stage runs against any OpenAI-compatible chat-completions model; the recommended default is Qwen3-30B-A3B-Thinking, a reasoning-tuned MoE model from Alibaba.

So when an agent hits a question outside its training cutoff, it doesn't hallucinate or shell out to a generic search tool. It calls discover to widen the source set, reads the top hits, and calls synthesize to fold the evidence into a citation-backed answer. Round-trip is typically 5–15 seconds against a hosted reasoning model.

Features

Tools (MCP and REST)

The MCP server exposes two primitives plus four deep-research tools — six tools total. The primitives give you raw search and the simple combined pipeline; the deep-research tools split discovery, synthesis, and reasoning so each step can be driven independently.

Primitives

| Tool | Purpose | |---|---| | search | Raw multi-source aggregation across SearXNG, Tavily, and LinkUp with RRF fusion. No LLM call. | | research | Combined pipeline: multi-source search plus LLM synthesis with citations, in one call. |

Deep-research tools

| Tool | Purpose | |---|---| | discover | Exploratory expansion — surfaces explicit, implicit, related, and contrasting angles, then flags knowledge gaps | | synthesize | Citation-aware synthesis over pre-gathered content; CRAG-style quality gate, contradiction surfacing, outline-guided generation | | reason | Deep synthesis with optional CoT depth control over pre-gathered content | | ask | Fast conversational answer (direct LLM call, no search hop) |

Pipeline

• Multi-source search: parallel queries across SearXNG, Tavily, and LinkUp with graceful degradation if any source is unavailable.
• RRF fusion: Reciprocal Rank Fusion combines and re-ranks results across providers.
• Adaptive routing: query classification picks the right combination of connectors per query.
• Query expansion: HyDE-style variant generation for broader coverage.
• Query decomposition: multi-aspect breakdown for complex queries.
• Quality gate: CRAG-style filtering keeps low-quality sources out of synthesis, or fails open with a low-relevance caveat when only weak sources are available (rather than refusing).
• Contradiction detection: PaperQA2-style disagreement surfacing flags conflicting claims rather than averaging them out.
• Citation binding: VeriCite-style claim-to-evidence mapping in the final answer.
• Outline-guided synthesis: SciRAG-style structured generation for tutorial and academic presets.
• Output verification: post-synthesis hard-gate on empty, truncated, reasoning-only, or uncited synthesis output — failed outputs are flagged with a verdict header and not cached, rather than being relayed as clean successes. Soft conditions (partial citation coverage, surfaced contradictions) append an advisory note.
• Focus modes: general, academic, documentation, comparison, debugging, tutorial, news.

Compatibility

• Reasoning models: works with Qwen3-Thinking, DeepSeek-R1, Qwen-QwQ, and any other OpenAI-compatible chat-completions model.
• Multi-tenant: accepts a per-request X-OpenRouter-Api-Key header so multiple users can share one server instance and bill their own OpenRouter accounts.
• MCP and REST: the same orchestration logic powers both surfaces.

What the full install includes

The Quick Starts below cover the orchestrator MCP — one of seven in the full stack. The complete deep research workflow (automatic per-query routing across the whole stack) comprises four parts:

1. Seven MCPs. This repo's orchestrator (gigaxity-deep-research) plus the Triple Stack (context7 + exa + jina — search/docs/code trio) plus three more (exa-answer, brightdata_fallback, gptr-mcp).
2. Companion projects and dependencies. SearXNG (primary search source, bundled at [companions/searxng/](companions/searxng/)) and GPT Researcher (transitive dependency of gptr-mcp); plus the minimal MCP wrappers bundled at [companions/exa-answer/](companions/exa-answer/) and [companions/brightdata-fallback/](companions/brightdata-fallback/).
3. The pasteable instruction block in [CLAUDE.md](CLAUDE.md#instruction-block--paste-into-your-harnesss-global-claudemd--agentsmd-or-system-prompt) — drop into the global CLAUDE.md / AGENTS.md your harness loads (e.g. ~/.claude/CLAUDE.md for Claude Code), or paste into a standalone agent's system prompt. The agent then fires the research workflow on external-knowledge queries and routes each query class to the right MCP.
4. The bundled [research-workflow](skills/research-workflow/SKILL.md) skill — the deep reference for the routing classifier (token costs per tool, presets, fallback chains).

Walk the [Setup roadmap](#setup-roadmap) below for a stage-by-stage path through all four.

Quick start: MCP install (Claude Code walkthrough)

The example below registers the server with Claude Code via ~/.claude.json. The same MCP stdio config block works for any MCP-capable harness (Codex, Cursor, Hermes, Continue.dev, etc.) — substitute that harness's config file path. For standalone agents that don't have an MCP harness, run the REST API instead (see the next quick start).

# Clone and install
git clone https://github.com/yoloshii/gigaxity-deep-research.git
cd gigaxity-deep-research

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

# Configure
cp .env.example .env
# Edit .env: set RESEARCH_LLM_API_KEY (https://openrouter.ai/keys)
#            and RESEARCH_SEARXNG_HOST (or leave default)

Add to ~/.claude.json under mcpServers:

"gigaxity-deep-research": {
  "type": "stdio",
  "command": "/path/to/gigaxity-deep-research/.venv/bin/python",
  "args": ["/path/to/gigaxity-deep-research/run_mcp.py"],
  "env": {
    "RESEARCH_LLM_API_BASE": "https://openrouter.ai/api/v1",
    "RESEARCH_LLM_API_KEY": "YOUR_OPENROUTER_API_KEY",
    "RESEARCH_LLM_MODEL": "qwen/qwen3-30b-a3b-thinking-2507"
  }
}

Restart Claude Code. The six tools (search, research, ask, discover, synthesize, reason) become callable as mcp__gigaxity-deep-research__.

The MCP alone gives you raw access to the six tools. Most of the deep research value — automatic per-query tool routing across the full seven-MCP stack, the social-first layer via gptr-mcp, the routing skill, and the global agent-instruction block — comes from the rest of the staircase. Walk it in [Setup roadmap](#setup-roadmap) below.

Quick start: REST API for distributed compute

When the model lives on a different machine from the orchestrator (e.g. you self-host the model on a GPU box and want the rest of the pipeline on a CPU-only edge node), run it as a REST API.

docker compose up -d
curl http://localhost:8000/api/v1/health

REST endpoints:

| Endpoint | Method | Purpose | |---|---|---| | /api/v1/health | GET | Health check, lists active connectors | | /api/v1/discover | POST | Exploratory expansion | | /api/v1/synthesize | POST | Citation-aware synthesis | | /api/v1/reason | POST | Chain-of-thought reasoning | | /api/v1/ask | POST | Quick answer | | /api/v1/research | POST | Combined search + synthesis | | /api/v1/search | POST | Multi-source search only (no LLM) | | /api/v1/presets | GET | List synthesis presets | | /api/v1/focus-modes | GET | List focus modes |

Each endpoint accepts an optional X-OpenRouter-Api-Key header that overrides the env-configured key for that request. Multi-tenant deployments use it to bill each user separately.

Full REST reference: [docs/reference/rest-api.md](docs/reference/rest-api.md).

Setup roadmap

The Quick Starts above get the orchestrator MCP running against a model and a search source. The full deep research workflow — automatic tool routing across the seven-MCP stack, social-first research via gptr-mcp, the routing skill that classifies queries, plus the agent-instruction block that wires it all into Claude Code — needs the rest of the staircase below.

Each stage has a verify step, so you can stop at any point and know the layer below is solid. Stages 1–4 give you a working orchestrator. Stages 5–7 turn it into the full deep research stack.

| # | Stage | What you do | Verify | Time | Doc | |---|---|---|---|---|---| | 1 | Core install | Clone repo, create venv, pip install -e . | python -c "from src.main import app" exits 0 | 2 min | [Quickstart](docs/quickstart.md) | | 2 | Primary search source | Stand up SearXNG (bundled compose file under [companions/searxng/](companions/searxng/)) | curl http://localhost:8888/healthz returns 200 | 5 min | [setup-companions.md](docs/guides/setup-companions.md) | | 3 | LLM endpoint | Start a local model (vLLM / SGLang / llama.cpp) or point env vars at a hosted endpoint such as OpenRouter | curl $RESEARCH_LLM_API_BASE/models returns a model list | 5–30 min | [setup-local-inference.md](docs/guides/setup-local-inference.md) | | 4 | Wire gigaxity into Claude Code | cp .env.example .env, edit env vars, register the stdio MCP block in ~/.claude.json, restart Claude Code | /mcp shows gigaxity-deep-research with a green dot; mcp__gigaxity-deep-research__research returns a synthesis with citations | 5 min | [setup-mcp.md](docs/guides/setup-mcp.md) | | 5 | Companion MCPs (Triple Stack) | Register Context7, Exa, Exa Answer, Jina, Brightdata fallback, and gptr-mcp in ~/.claude.json | /mcp shows all seven MCPs registered with green dots | 10–15 min | [triple-stack-setup.md](docs/guides/triple-stack-setup.md) | | 6 | Routing skill + agent instructions | Symlink [skills/research-workflow/](skills/research-workflow/) into your skills dir; paste the instruction block from [CLAUDE.md](CLAUDE.md#instruction-block--paste-into-your-harnesss-global-claudemd--agentsmd-or-system-prompt) into your harness's global CLAUDE.md / AGENTS.md (or a standalone agent's system prompt) | A research query triggers the research-workflow skill instead of the agent's built-in WebSearch | 3 min | [skill SKILL.md](skills/research-workflow/SKILL.md) | | 7 | Full-stack smoke | Run one query of each routing class and confirm the right MCP fires | See the smoke matrix below | 5 min | (below) |

Smoke matrix

Run each query in Claude Code (or the agent of your choice) after Stage 7 and confirm the routing matches:

| Query | Should route to | What you should see | |---|---|---| | "What's the latest stable version of Bun?" | exa-answer | 1–2 s factual answer with citations | | "What does the OpenAI Python SDK's client.beta namespace cover?" | context7 (resolve-library-id → query-docs) | Library/API documentation chunks | | "Show me a code example using httpx.AsyncClient with retries" | exa (get_code_context_exa) | Curated code-context snippets | | "Find recent papers on CRAG quality gates" | jina (search_arxiv) | arXiv search hits | | "Compare FastAPI vs Litestar for production APIs in 2026" | gigaxity-deep-research (synthesize) | Citation-backed comparative synthesis | | "What do people on Reddit say about Bun vs Node for production?" | gptr-mcp (quick_search) | Reddit / X / YouTube community sentiment |

If a query routes somewhere unexpected, the most common cause is the global instruction block from Stage 6 not being pasted into your global CLAUDE.md / AGENTS.md. Without it, the agent has to discover the routing logic on its own per session.

Common pitfalls

• Stage 2 is required, not optional. SearXNG is the only required search connector — Tavily and LinkUp are optional additional connectors that run in parallel and contribute to RRF fusion. Skipping SearXNG leaves the synthesis layer with nothing to fuse unless you configure Tavily or LinkUp as a substitute.
• Verify Stage 4 before adding companions. A failing research call after Stage 5 is hard to debug because the failure could be any of seven MCPs misfiring; confirm the orchestrator alone works first.
• Stage 6 is what makes the agent route automatically. Without the skill plus the instruction block, the seven MCPs are visible but the agent treats them as raw tools, not a stack.
• local-inference branch defaults to http://localhost:8000/v1; main defaults to OpenRouter. Stage 3's verify command is the same either way, but the env var values differ — match them to your branch.

Modes

| Mode | Branch | LLM backend | When to use | |---|---|---|---| | OpenRouter (default) | main | Hosted Qwen3-30B-A3B-Thinking via OpenRouter | Single-machine setup, no GPU, fastest path to working | | Local inference (env-override today; code-level swap pending — see Roadmap) | local-inference (placeholder branch, currently mirrors main) | Self-hosted Qwen3/DeepSeek/Llama via vLLM, SGLang, or any OpenAI-compatible server | On-prem requirement, GPU available, no usage-based cost. Works on either branch today by setting RESEARCH_LLM_API_BASE to any OpenAI-compatible endpoint. | | REST API (any backend) | both | Either, plus optional re

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yoloshii
• Source: yoloshii/gigaxity-deep-research
• License: MIT

Install and usage instructions live in the source repository linked above.