> ## Documentation Index
> Fetch the complete documentation index at: https://docs.consensus.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start: Search & Threads

> The two ways an assistant uses Consensus MCP: search for ranked papers in one call, or hand a research question to the Consensus research agent with Threads.

Consensus MCP gives your assistant two ways to work with the literature:

* **Search:** the `search` tool returns ranked papers in one call. Your assistant reads them and writes the answer.
* **Threads:** the thread tools hand the whole research question to the Consensus research agent. The agent searches, reads the papers, and writes a cited answer. Your assistant starts the Thread, waits for it, and shows the result.

Ask your question in plain language and your assistant picks the right tool for it. To make it use a specific one, say so in your prompt: for example, "Search Consensus for…" for search, or "Start a Consensus research thread on…" for a Thread.

## Search vs Threads

| | Search | Threads |
| - | - | - |
| **Tools** | [`search`](https://docs.consensus.app/mcp-tools/search), then [`get_full_text`](https://docs.consensus.app/mcp-tools/get-full-text) to read open-access papers in full | [`create_thread`](https://docs.consensus.app/mcp-tools/create-thread), [`get_thread`](https://docs.consensus.app/mcp-tools/get-thread), [`add_to_thread`](https://docs.consensus.app/mcp-tools/add-to-thread), [`find_threads`](https://docs.consensus.app/mcp-tools/find-threads) |
| **Your assistant gets back** | Ranked papers with abstracts and metadata | A written analysis with inline citations, grounding quotes, and the cited papers |
| **Functionality** | Semantic paper search with filters | Search, citation crawls, author search, finding specific papers, reading full papers, searching attached papers and collections, and saving papers to your Library |
| **Steps per request** | One | Many |
| **Timing** | Seconds | Minutes. The assistant polls until the answer is ready |
| **Follow-ups** | Each call stands alone | Follow-ups build on the earlier answers in the same Thread |
| **Account** | Works without an account at reduced limits | Requires a signed-in Consensus account or API key |

Need a quick lookup, or papers for your assistant to reason over? Use search. Need a researched, cited answer to a question that takes several steps? Use a Thread.

## Search

Your assistant calls `search` with a query and any filters you asked for, then answers from the ranked papers it gets back.

Try asking:

* "Find RCTs and meta-analyses since 2020 on cognitive behavioral therapy for anxiety"
* "Search for human studies on gut microbiome and mental health with at least 100 participants"
* "Recent research on large language model hallucination from Q1 journals"

See the [`search` tool reference](https://docs.consensus.app/mcp-tools/search) for every filter.

### Read whole papers

When the abstract and excerpts aren't enough, your assistant can read a paper's complete text. Each search result shows an `id:` line, marked `full text available` when the paper is open access and `get_full_text` is available to you. Your assistant passes up to 3 of those ids, a Thread citation's `paper_id`, or DOIs, to [`get_full_text`](https://docs.consensus.app/mcp-tools/get-full-text) and gets each paper back as Markdown. It costs 1 credit per paper returned and needs a paid plan.

* "Read the methods section of the largest RCT in those results."
* "Get the full text of 10.2903/j.efsa.2024.9100 and list every dose it reports."

## Threads

Threads are asynchronous. A `pro` run usually finishes in under a minute, and a `deep` run takes a few minutes.

**1. Start a Thread**

Your assistant calls [`create_thread`](https://docs.consensus.app/mcp-tools/create-thread) with the complete research brief. It returns a `thread_id` and a link to the Thread in Consensus right away, with `status: "running"`.

**2. Wait for the answer**

Your assistant calls [`get_thread`](https://docs.consensus.app/mcp-tools/get-thread) about every 5 seconds for `pro` and every 20 seconds for `deep`, until `status` is `idle` (answer ready) or `failed`. A `pro` run usually finishes in under a minute. A `deep` run takes about 2 to 4 minutes, and occasionally up to about 10.

**3. Show the result**

When the Thread is `idle`, `get_thread` returns the analysis as a ready-to-write markdown document with a References section. Most assistants write it to a file, artifact, or canvas and reply with a short summary plus the Consensus link.

**4. Ask a follow-up**

[`add_to_thread`](https://docs.consensus.app/mcp-tools/add-to-thread) continues the same Thread. The agent keeps the earlier context, so you don't need to restate it.

To pick up an earlier Thread, ask your assistant to find it. [`find_threads`](https://docs.consensus.app/mcp-tools/find-threads) lists your Threads and can match on title.

### What you can ask a Thread

Each of these takes several research steps, which a single search can't do.

> [card] Crawl citations
>
> "Start from Cong et al. 2013, the first report of CRISPR-Cas9 editing in mammalian cells. Trace the work it built on and the most-cited papers that followed, and summarize how the method evolved."

> [card] Research an author
>
> "Summarize Walter Willett's research on dietary fat and heart disease, and how his conclusions changed over time."

> [card] Run deep research
>
> "Do a deep literature review on GLP-1 receptor agonists and cardiovascular outcomes. Cover mechanisms, the major trials, safety signals, and open questions."

> [card] Save papers to your Library
>
> "Find 10 RCTs on magnesium and sleep quality and save them to my Sleep collection."

> [card] Build on an earlier answer
>
> "Of the trials you cited, keep only RCTs with more than 100 participants. Does the conclusion change?"

## Good to know

* **Account:** the thread tools appear only for a signed-in Consensus account, over OAuth or an [API key as a Bearer token](https://docs.consensus.app/consensus-mcp.md#connect-your-client). Without an account, your assistant sees only `search`.
* **Deep mode:** `deep` reads about 50 papers and writes a longer, structured report. It requires a paid plan, and your assistant uses it only when you ask for a deep or comprehensive review.
* **Cost:** search costs one call per 100 papers returned, and `get_full_text` 1 credit per paper returned. A Thread draws from the same monthly calls and is charged by the amount of work the agent does, so a `deep` run costs more than a `pro` run. A failed run costs nothing. See [plans and access](https://docs.consensus.app/mcp-plans-and-access.md#how-calls-are-counted).
* **In Consensus:** a Thread started from your account also appears in Consensus, with the interactive consensus meter and citation graph. Open it from the `url` link.
* **Same as the API:** the thread tools run the same research agent as the [Threads API](https://docs.consensus.app/api-quickstart-threads.md).

## Tool reference

> [card] [search](https://docs.consensus.app/mcp-tools/search.md)
>
> Find ranked papers for a query in one call.

> [card] [get\_full\_text](https://docs.consensus.app/mcp-tools/get-full-text.md)
>
> Read the complete text of open-access papers.

> [card] [create\_thread](https://docs.consensus.app/mcp-tools/create-thread.md)
>
> Start a Thread with the research agent.

> [card] [get\_thread](https://docs.consensus.app/mcp-tools/get-thread.md)
>
> Poll a Thread and read the cited answer.

> [card] [add\_to\_thread](https://docs.consensus.app/mcp-tools/add-to-thread.md)
>
> Ask a follow-up in an existing Thread.

> [card] [find\_threads](https://docs.consensus.app/mcp-tools/find-threads.md)
>
> List your Threads and find an earlier one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.