> ## 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`](/mcp-tools/search) | [`create_thread`](/mcp-tools/create-thread), [`get_thread`](/mcp-tools/get-thread), [`add_to_thread`](/mcp-tools/add-to-thread), [`find_threads`](/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](/mcp-tools/search) for every filter.

## Threads

Threads are asynchronous. Each run takes minutes, not seconds.

<Steps>
  <Step title="Start a Thread">
    Your assistant calls [`create_thread`](/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"`.
  </Step>

  <Step title="Wait for the answer">
    Your assistant calls [`get_thread`](/mcp-tools/get-thread) about every 30 seconds until `status` is `idle` (answer ready) or `failed`. A `pro` run usually finishes within about 3 minutes, and a `deep` run within about 10 minutes.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Ask a follow-up">
    [`add_to_thread`](/mcp-tools/add-to-thread) continues the same Thread. The agent keeps the earlier context, so you don't need to restate it.
  </Step>
</Steps>

To pick up an earlier Thread, ask your assistant to find it. [`find_threads`](/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.

<CardGroup cols={2}>
  <Card title="Crawl citations" icon="network">
    "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>

  <Card title="Research an author" icon="user">
    "Summarize Walter Willett's research on dietary fat and heart disease, and how his conclusions changed over time."
  </Card>

  <Card title="Run deep research" icon="layers">
    "Do a deep literature review on GLP-1 receptor agonists and cardiovascular outcomes. Cover mechanisms, the major trials, safety signals, and open questions."
  </Card>

  <Card title="Save papers to your Library" icon="folder-plus">
    "Find 10 RCTs on magnesium and sleep quality and save them to my Sleep collection."
  </Card>

  <Card title="Build on an earlier answer" icon="messages-square">
    "Of the trials you cited, keep only RCTs with more than 100 participants. Does the conclusion change?"
  </Card>
</CardGroup>

## 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](/consensus-mcp#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. 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](/mcp-plans-and-access#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](/api-quickstart-threads).

## Tool reference

<CardGroup cols={2}>
  <Card title="search" icon="search" href="/mcp-tools/search">
    Find ranked papers for a query in one call.
  </Card>

  <Card title="create_thread" icon="plus" href="/mcp-tools/create-thread">
    Start a Thread with the research agent.
  </Card>

  <Card title="get_thread" icon="refresh-cw" href="/mcp-tools/get-thread">
    Poll a Thread and read the cited answer.
  </Card>

  <Card title="add_to_thread" icon="message-square-plus" href="/mcp-tools/add-to-thread">
    Ask a follow-up in an existing Thread.
  </Card>

  <Card title="find_threads" icon="list" href="/mcp-tools/find-threads">
    List your Threads and find an earlier one.
  </Card>
</CardGroup>


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