Sibyl — Deep Research MCP

English · 简体中文

Quick start · How it works · Workflow · Evaluation · Docs

A research MCP for your AI agent: investigate across sources, inspect evidence, track counterevidence and gaps, and export a cited report when needed.

Your agent does the searching and thinking. Sibyl gives it a persistent research workspace alongside its own search; it does not replace it. Connect it to a local MCP-capable agent you already use, including one backed by a subscription. Sibyl does not call another generative model, read subscription credentials, or require a second model API key. The host's own usage rules still apply.

[!NOTE]

Status (2026-10-28): development paused; no stable release is planned.

The preregistered paired evaluation did not pass in either of two runs:

pooled, an agent using Sibyl cited sources that supported its claims somewhat

more often (79.4% against 74.9%) than the same agent with only built-in search,

at about twice the cost, a difference within run-to-run noise

(details). Agents' own research has caught up with

what Sibyl set out to add. This README describes the source checkout; published

beta 0.4.0b1 and stable 0.3.0 contain older architectures.

What it does

A search call returns leads. Sibyl keeps the investigation connected.

The host chooses queries, reads sources and judges what they support. Sibyl retrieves, preserves state, checks reference integrity and enforces budgets. It does not decide truth for the host or run an autonomous researcher.

When to use it: when a conclusion must be checked or reused, such as a decision that needs cited evidence, a comparison that should include counterevidence, an investigation spanning several questions or sessions, findings handed to someone else, or a report. For a quick fact lookup, your agent's own search is enough: Sibyl adds steps, and pays off only when the evidence trail matters.

How it works

sequenceDiagram

autonumber participant H as AI agent (MCP host) participant S as Sibyl participant W as Public web H->>W: Own web search H->>S: start_research, continue_research(url) S->>W: Safe fetch, extract, cluster, rank S-->>H: Update: top passages, gaps, next searches H->>S: assess_research: claims with exact quotes S-->>H: Quote checks, claim support, counterevidence status H->>S: complete_research, save_report S-->>H: Cited report (Markdown, JSON or PDF)

The default MCP surface has eight tools, compact structured briefs, per-question updates after each read or assessment, and on-demand passage reads. A research result does not need to become a long report before another agent can use it.

Quick start

Requires Python 3.11+ and a host supporting local stdio MCP. Install this source checkout in a fresh environment:

git clone https://github.com/chriswu727/sibyl.git

cd sibyl python -m venv .venv .venv/bin/python -m pip install -e . .venv/bin/sibyl-mcp --list-tools # should list eight tools

Add Sibyl to your host's MCP configuration, replacing both paths with absolute local paths. SIBYL_OUTPUT_ROOT is optional; without it, research is stored in your per-user data directory and shared by your local sessions:

{

"mcpServers": { "sibyl": { "command": "/absolute/path/to/sibyl/.venv/bin/sibyl-mcp", "env": { "SIBYL_OUTPUT_ROOT": "/absolute/path/to/private-sibyl-research" } } } }

Then ask your agent:

Use Sibyl to investigate whether SQLite WAL fits a multi-process application.

Inspect the original documentation, investigate limitations and counterevidence,

and return evidence-linked conclusions with unresolved questions. Write a report

only if I ask for one.

Windows, search keys and transport notes

• On Windows, use .venv\Scripts\sibyl-mcp.exe. Configuration syntax varies by host; the example is for clients accepting mcpServers JSON.
• Results arrive as MCP structuredContent mirrored as JSON text, so hosts that pass only text to the model still receive them. The former --profile keyless text surface was removed. This is not a remote HTTP MCP endpoint.
• No search key is required. Optional Tavily search has separate credentials and provider charges; subscription access to your agent does not pay for Tavily. See installation and optional integrations.

Research workflow

1. Start with question and sub_questions.
2. Read sources found by your agent's own search with continue_research(url=..., query=...); a query alone uses Sibyl's keyless search. Link each retrieval to question_id, and use purpose="counterevidence" for an actual investigation of alternatives. Each read returns an update with the new sources' top passages inline and the question's gaps and next searches.
3. Inspect exact text before assessing: the full brief omits raw text, so read up to twelve passages at once with get_research(job_id, passage_ids=[...]).
4. Assess with stable supporting/challenging passage IDs, a conclusion and claims. Facts link exact passages and quote them; Sibyl rejects a quote it cannot find in the cited passage. Reasoning links its premises, recommendations state criteria and assumptions, and unknowns stay explicit. See the claim contract and complete example.
5. Iterate on the gaps in research_plan with a focused query and rationale, then reassess.
6. Report only if needed: complete_research with the current revision, then save_report(job_id=..., format="md").

More on assessments, reports and recovery

Quote matching ignores only case, spacing, accent encoding and typographic variants; numbers are never folded. Changes to a premise or new retrieval make dependent judgments need reassessment. Use get_research(view="sources", revision=..., offset=0, limit=10) to page evidence outside the selected citation window.

For JSON as well as Markdown, call save_report again with format="json" and use its returned path. Exports return a machine-readable manifest with confirmed file paths, formats, sizes, hashes and per-format failures. Errors expose recovery instructions and the current saved revision when available; rejected claims are never silently accepted. See the agent protocol.

Sibyl renders the host-authored claims and citations, including their premises, criteria and assumptions. Unknown and disputed claims remain visible even if omitted from the selection. Old contract-1 jobs can no longer be finalized. Citation validation checks targets, not whether the text entails the claim. Incomplete research must retain its gaps; allow_incomplete=true yields a partial report. A completed job means the report is finalized, not that its claims are true.

Detailed workflow and limits · Machine-facing contract

See an investigation

Read the report · Inspect the evidence · Reproduce the replay

This is a recorded-source MCP replay with host-authored reasoning, not a live accuracy benchmark. It checks gap reviews, counterevidence, exports and restart. The ten-case live host suite separately documents discovery failures, host-supplied URLs and explicit abstention.

Optional capabilities

.venv/bin/python -m pip install -e '.[pdf]'      # text-PDF input; POSIX only

.venv/bin/python -m pip install -e '.[report]' # PDF output, no model SDK .venv/bin/python -m pip install -e '.[monitor]' # authenticated loopback monitoring

Markdown and JSON export need no extra. [extract] supplies Trafilatura for compatibility reads; [rerank] supplies optional local FlashRank ranking. The default lexical ranker needs no model download. See usage and operations. For inspection outside an agent, use sibyl gather "a focused question" --format json or the async Python sibyl.gather_bundle API. Neither generates an answer.

Upgrading from the old architecture

LiteLLM, model-provider configuration, autonomous execution, generic model analysis, SWOT/timeline generation and finance/chart tools have been removed. The report extra now means PDF rendering only. Sibyl serves one tool set; the old keyless, report, finance and full profiles are rejected.

Install in a fresh virtual environment: upgrading a package does not uninstall its old transitive dependencies. Remove old model settings from SIBYL_CONFIG. Do not give Sibyl your host's login token. Existing checkpoints remain readable and completed reports exportable; old autonomous jobs cannot resume execution. Start a new host job to continue investigating. See migration. The legacy-boundary inventory distinguishes removed execution from retained checkpoint/report readers and historical evaluation evidence.

Quality and limitations

The practical difference is persistent, evidence-directed research, not a claim to have a better model. Ev