Skip to main content
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

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. 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 for every filter.

​
Threads

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

Start a Thread

Your assistant calls 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 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.
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 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 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.

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.”

Research an author

“Summarize Walter Willett’s research on dietary fat and heart disease, and how his conclusions changed over time.”

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.”

Save papers to your Library

“Find 10 RCTs on magnesium and sleep quality and save them to my Sleep collection.”

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. 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.
  • 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.

​
Tool reference

search

Find ranked papers for a query in one call.

create_thread

Start a Thread with the research agent.

get_thread

Poll a Thread and read the cited answer.

add_to_thread

Ask a follow-up in an existing Thread.

find_threads

List your Threads and find an earlier one.