Get started with Consensus MCP

The Consensus MCP server enables AI assistants like ChatGPT, Claude, Gemini Spark, and other MCP-compatible clients to search over 220 million peer-reviewed academic research papers directly from the conversation.

Consensus MCP lets AI assistants search 220+ million peer-reviewed research papers. Connect your preferred client below. You’ll be searching in under 2 minutes.

Server URL

https://mcp.consensus.app/mcp

Claude

Add Consensus from the Claude connectors directory.

ChatGPT

Add Consensus from the ChatGPT app directory.

Connect Your Client

Claude Desktop

One-click: open Consensus in the Claude directory and click Connect. Or connect manually:

1. Open Settings

   Open claude.ai or the Claude desktop app and go to Settings.

2. Browse connectors

   Select Connectors, then Browse connectors.

3. Find Consensus

   Search for Consensus and click Connect.

4. Sign in

   Approve the sign-in with your Consensus account, or continue without one at reduced limits.

5. Start searching

   Ask a research question in any chat. Consensus appears in the tools menu.

Claude Code

claude mcp add --transport http consensus https://mcp.consensus.app/mcp

OAuth will open in your browser automatically on first use. You can also trigger it manually with the /mcp command inside Claude Code.

ChatGPT

One-click: open Consensus in the ChatGPT app directory and click Connect. Or connect manually:

1. Open ChatGPT

   Open chatgpt.com and sign in.

2. Find Consensus

   Open Apps from the sidebar, search for Consensus, and click Connect.

3. Sign in

   Sign in with your Consensus account when prompted.

4. Start searching

   Ask a research question, or call it by name: “Use Consensus to find RCTs on…”

Search results display in an interactive widget showing top papers with citations and direct links.

Consensus also works with ChatGPT Deep Research. See Using Consensus with ChatGPT Deep Research below.

Codex

codex mcp add consensus --url https://mcp.consensus.app/mcp
codex mcp login consensus

Or add to ~/.codex/config.toml:

[mcp_servers.consensus]
url = "https://mcp.consensus.app/mcp"

Cursor

One-click: Install in Cursor. Or add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "consensus": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.consensus.app/mcp"]
    }
  }
}

VS Code (GitHub Copilot)

Add to your MCP configuration:

{
  "servers": {
    "consensus": {
      "url": "https://mcp.consensus.app/mcp"
    }
  }
}

Windsurf

Add to your MCP configuration:

{
  "mcpServers": {
    "consensus": {
      "serverUrl": "https://mcp.consensus.app/mcp"
    }
  }
}

Gemini Spark

Add Consensus as a custom app for Gemini Spark:

1. Open Connected Apps

   Go to gemini.google.com and sign in with a personal Google Account, then click Settings & help → Connected Apps.

2. Add a custom app

   Under Custom apps for Spark, click Add a custom app and paste the server URL:

   https://mcp.consensus.app/mcp
   
3. Approve the connection

   Click Next and follow the prompts to finish OAuth. If your client doesn’t support Dynamic Client Registration, expand Advanced features and enter your credentials.

4. Start searching

   Ask Gemini Spark a research question and it can call Consensus tools.

Requires access to Gemini Spark, a personal Google Account, Keep Activity turned on, and is currently available in the US. Workspace and school accounts are not supported yet.

Other MCP clients

Any client that supports remote MCP servers (Streamable HTTP) works. Point it at https://mcp.consensus.app/mcp. If your client supports OAuth, authentication is handled automatically.

Watch: connect Consensus and run your first search

Using Consensus with ChatGPT Deep Research

Consensus also works with ChatGPT Deep Research. When Deep Research uses the Consensus app, it can search Consensus for relevant papers and retrieve full paper details for cited results.

1. Connect the Consensus app

   Connect the Consensus app in ChatGPT using the steps above.

2. Start a Deep Research request

   Start a Deep Research request in ChatGPT.

3. Ask ChatGPT to use Consensus

   Ask ChatGPT to use Consensus for peer-reviewed research, for example:

   Use Consensus to research the evidence on exercise for depression. Prioritize systematic reviews, meta-analyses, and randomized controlled trials.

Deep Research may run multiple Consensus searches, refine filters, retrieve paper details, and return a cited synthesis with direct links to papers on Consensus.

Verify Your Connection

Try one of these in your connected client. Each link opens the question pre-filled:

Ask	Try it
”What does the research say about creatine and cognitive function?”	Claude · ChatGPT
”Find meta-analyses on mindfulness for anxiety published since 2020”	Claude · ChatGPT
”Are there RCTs on intermittent fasting with more than 500 participants?”	Claude · ChatGPT
”What is the strongest evidence for and against remote work productivity?”	Claude · ChatGPT

You should see results citing specific papers with titles, journals, years, citation counts, and direct links.

Plans and Access

Your results depend on your Consensus plan, not your AI subscription (Claude Pro, ChatGPT Plus, etc. have no effect on Consensus results).

No account is needed to get started. Connect directly and try it out.

Plan	Max Page Size	Included Monthly Searches	Extra Features
No Account	3	Unlimited	None
Free	10	30	Full abstracts
Pro	300	250	Study type, key takeaways
Deep	750	1,000	Study type, key takeaways
Teams	300	250	Study type, key takeaways

Max Page Size is the per-request ceiling. Requests that omit page_size still return the default of 20 papers.

Paid plans can search beyond the included monthly limit when the account has an active metered API subscription and additional usage is enabled; those extra searches are billed to the subscription. Free plans are capped at the included limit.

Create a free account at consensus.app/sign-up or upgrade at consensus.app/pricing.

Enterprise and API Key Access

For enterprise access with unlimited rate limits, include your API key as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Contact Consensus for enterprise API access at consensus.app/home/api.

Search Tool

The search tool searches Consensus for peer-reviewed research papers. ChatGPT Deep Research may call this tool multiple times with different queries and filters while building a research report.

Parameters

Parameter	Type	Required	Description
query	string	Yes	The research question or topic to search for. Use specific academic terminology for best results.
year_min	integer	No	Exclude papers published before this year.
year_max	integer	No	Exclude papers published after this year.
study_types	string array	No	Filter by study design. Values: rct, meta-analysis, systematic review, literature review, case report, non-rct experimental, non-rct observational study, non-rct in vitro, animal.
sjr_max	integer	No	Filter by journal quality (SCImago Journal Rank quartile). 1 is Q1 (highest), 2 is Q2, 3 is Q3, 4 is Q4.
sjr_min	integer	No	Minimum journal ranking quartile. 1 is Q1 (highest), 4 is Q4. Excludes better (lower-number) quartiles; for example, set to 2 to keep Q2–Q4.
human	boolean	No	Set to true to include only studies involving human subjects.
controlled	boolean	No	Set to true to include only controlled studies.
sample_size_min	integer	No	Exclude studies with sample sizes smaller than this number.
citation_min	integer	No	Exclude papers with fewer citations than this number.
medical_mode	boolean	No	Set to true for clinical, medical, or evidence-based medicine questions. Prioritizes top medical journals and clinical guidelines.
exclude_preprints	boolean	No	Set to true to exclude preprints and return peer-reviewed papers only.
open_access	boolean	No	Set to true to include only open-access papers.
duration_min	integer	No	Minimum study duration in days. Useful for longitudinal or long-term studies.
duration_max	integer	No	Maximum study duration in days.
country	string	No	Comma-separated ISO 3166-1 alpha-2 country codes (for example us, gb) to limit to those countries of study. Unknown codes are ignored.

Response

Each search returns:

papers · array

Array of paper objects with title, authors, abstract, journal, year, citation_count, and url (direct link to the paper on Consensus).

total_results · integer

Total number of papers found.

query · string

The original search query.

Pro plans and above also include study_type and takeaway for each paper. Enterprise includes doi.

Example Prompts

• “What does the research say about the effectiveness of remote work on productivity?”
• “Find RCTs and meta-analyses since 2020 on cognitive behavioral therapy for anxiety”
• “Search for high quality human studies on gut microbiome and mental health with at least 100 participants”
• “Recent research on large language model hallucination from top tier journals”
• “Use Consensus Deep Research to compare evidence for different treatments for insomnia”

Research threads

The thread tools run multi-step, citation-grounded research for synthesis, comparison, contradiction, and literature-review questions. You create a thread, poll it with get_thread, and list threads with find_threads. Research threads require a signed-in Consensus account; deep mode requires a paid plan.

Use the search tool for a simple paper list. Use thread tools when you need a synthesized, multi-step answer with inline citations.

create_thread

Starts a new research thread and dispatches the Consensus agent.

Parameter	Type	Required	Description
input_message	string	Yes	Your complete research brief. Include the whole question, scope, population, timeframe, comparisons, constraints, and desired output in one call.
mode	string	No	pro (default, ~20 papers, fast) or deep (~50 papers, up to 100, structured literature review). Use deep only when the user explicitly asks for an exhaustive review.
filters	object	No	Same structured filters as the search tool.
attachments	object	No	{"paper_attachments": [{"paper_id": "...", "es_hash_paper_id": "..."}], "collection_ids": [123]}.

Returns a dispatch confirmation with status running, plus thread_id, interaction_id, mode, url, poll_after_seconds, max_wait_seconds, and next_steps.

add_to_thread

Adds a new follow-up interaction to an existing thread.

Parameter	Type	Required	Description
thread_id	string	Yes	The thread_id returned by create_thread.
input_message	string	Yes	A new follow-up the user raised after seeing the previous result. Do not use this to continue your own plan.
mode	string	No	Same as create_thread.
title	string	No	Thread title from create_thread; used only for the deep-link label.
filters	object	No	Same as create_thread.
attachments	object	No	Same as create_thread.

Returns the same dispatch confirmation as create_thread.

get_thread

Polls a research thread and returns the grounded answer when ready.

Parameter	Type	Required	Description
thread_id	string	Yes	The thread_id returned by create_thread.
interaction_id	string	No	Hydrate only this interaction, for example the one returned by create_thread. Omit to hydrate the latest interaction. Returns an error if the id is not in the thread.
include_trace	boolean	No	Include a textual agent_trace and the raw agent_trace_raw graph for each interaction. Default is false.

The top-level response contains:

thread_id · string

The thread id.

title · string

Thread title.

filename · string

Sanitized filename for saving the document.

status · string

idle (ready), running (in progress), or failed.

url · string

Deep link to the thread in Consensus.

message_for_user · string

Status message with the Consensus link.

display_first · boolean

Always true; reproduce this message before any other output.

interactions · array

List of interactions.

Each interaction contains:

interaction_id · string

The interaction id.

input_message · string

The prompt for this turn.

created_at · string

When the interaction was created.

search_mode · string

Backend search mode value.

mode · string

pro, deep, or quick for legacy SUMMARY threads.

status · string

idle, running, or failed.

filters · object

Structured filters used for the turn.

full_text_paper_ids · array

Paper ids used as full-text context.

response · string

Clean markdown answer with hyperlinked [N] citation markers.

document · string

Ready-to-write markdown file with a ## References section. Only present when status is idle and citations were hydrated successfully.

citations · array

Hydrated paper metadata with n, title, authors, year, journal, doi, url, paper_id, and snippets.

cited_papers · array

Compact rank to paper_id mapping.

stats · object

PRISMA-style counts: retrieved, eligible, included.

step_count · integer

Number of visible agent trace nodes.

agent_trace · string

Text summary of the agent trace. Only present when include_trace is true.

agent_trace_raw · object

Full raw agent graph. Only present when include_trace is true.

When an interaction is running, document is omitted, citations is empty, and response is empty. When citation hydration fails, document is withheld so a degraded result is not marked ready.

Wait at least 30 seconds between get_thread calls. Pro results typically finish within ~3 minutes; Deep results may take up to ~10 minutes. Polling faster returns cached running results and does not speed up the agent.

find_threads

Lists the signed-in user’s research threads.

Parameter	Type	Required	Description
query	string	No	Optional title substring search. Leave empty to list all threads.
limit	integer	No	Maximum threads to return. Default 20, max 100.
offset	integer	No	Pagination offset. Default 0.

Returns threads and has_more. Each thread includes thread_id, title, status (idle, running, failed, or unknown), preview, interaction_count, last_activity_at, and url.

Troubleshooting

OAuth login is only supported for streamable HTTP servers (Codex)

You added the server with -- --transport http instead of --url. Remove and re-add:

codex mcp remove consensus
codex mcp add consensus --url https://mcp.consensus.app/mcp
codex mcp login consensus

Authentication successful but server reconnection failed (Claude Code)

Fully quit and restart Claude Code. Do not just use the reconnect option. Your credentials are saved and will work after restart.

Tools stop working after a few hours (401 errors)

Your OAuth token has expired. Re-authenticate:

• Claude Code: Type /mcp, select Consensus, choose Clear authentication, re-authenticate, then restart Claude Code
• Codex: Run codex mcp logout consensus then codex mcp login consensus
• Cursor: Disconnect and reconnect the server in Settings then Tools and MCP
• Claude Desktop: Disconnect and reconnect the connector in Settings then Connectors
• ChatGPT: Disconnect and reconnect the Consensus app from ChatGPT Apps

Server shows failed or no tools appear

• Verify the URL includes /mcp at the end
• Remove and re-add the server using the commands above
• Restart your client completely

Consensus search has not been loaded yet (Claude Code)

This is normal. Claude loads tool definitions on demand when many tools are present. Retry the query and it will work on the second attempt.

ChatGPT Deep Research is not using Consensus

Confirm the Consensus app is connected in ChatGPT Apps, then ask Deep Research to use Consensus explicitly. For example:

Use Consensus to find peer-reviewed papers on this question and cite the strongest evidence.

Deep Research decides when to call connected tools, so it may not call Consensus for questions that are not research-focused.

No results found

Try broadening your search query or removing filters. Use specific academic terminology rather than casual language.

Monthly search limit reached

Paid plans can continue searching past the included monthly limit when the account has an active metered API subscription and additional usage is enabled; those extra searches are billed to the subscription. Free plans must wait for the next monthly reset or upgrade.

Rate limit exceeded (429 error)

Wait a few moments before searching again. If using automated workflows, implement backoff logic between requests.

Security

• Endpoint: Only connect to the official URL: https://mcp.consensus.app/mcp
• API keys: Store securely using environment variables. Never share keys in prompts or public conversations. Rotate if compromised.
• Data handling: Search queries are sent to the Consensus API over HTTPS/TLS. Results contain publicly available academic paper metadata. No personal data is stored from MCP requests.

Supported Platforms

Platform	Auth	Status
Claude Desktop	OAuth	Supported
ChatGPT	OAuth	Supported
ChatGPT Deep Research	OAuth	Supported
Claude Code	OAuth	Supported
Codex	OAuth	Supported
Cursor	OAuth	Supported
VS Code (GitHub Copilot)	Config	Supported
Windsurf	Config	Supported
Gemini Spark	OAuth	Supported
Other MCP Clients	Bearer token	Supported

Additional Resources

Consensus Website

Explore the Consensus research platform.

API Documentation

Full reference for the Consensus search API.

MCP Specification

Learn more about the Model Context Protocol.

MCP server on GitHub

View the source, report issues, and star the Consensus MCP server.