> ## Documentation Index
> Fetch the complete documentation index at: https://consensus-f7e6ffce-devin-1787806026-mcp-add-to-thread.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
```
Add Consensus from the Claude connectors directory.
Add Consensus from the ChatGPT app directory.
## Connect Your Client
**One-click:** open [Consensus in the Claude directory](https://claude.ai/directory/65247229-f0c7-49df-9044-fcbb8b3894c6) and click **Connect**. Or connect manually:
Open [claude.ai](https://claude.ai) or the Claude desktop app and go to **Settings**.
Select **Connectors**, then **Browse connectors**.
Search for **Consensus** and click **Connect**.
Approve the sign-in with your Consensus account, or continue without one at reduced limits.
Ask a research question in any chat. Consensus appears in the tools menu.
```bash theme={null}
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.
**One-click:** open [Consensus in the ChatGPT app directory](https://chatgpt.com/plugins/plugin_asdk_app_6943e6f4a928819195962de16fb9ffe4) and click **Connect**. Or connect manually:
Open [chatgpt.com](https://chatgpt.com) and sign in.
Open **Apps** from the sidebar, search for **Consensus**, and click **Connect**.
Sign in with your Consensus account when prompted.
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](#using-consensus-with-chatgpt-deep-research) below.
```bash theme={null}
codex mcp add consensus --url https://mcp.consensus.app/mcp
codex mcp login consensus
```
Or add to `~/.codex/config.toml`:
```toml theme={null}
[mcp_servers.consensus]
url = "https://mcp.consensus.app/mcp"
```
**One-click:** [Install in Cursor](https://cursor.com/en/install-mcp?name=consensus\&config=eyJ1cmwiOiJodHRwczovL21jcC5jb25zZW5zdXMuYXBwL21jcCJ9). Or add to `~/.cursor/mcp.json`:
```json theme={null}
{
"mcpServers": {
"consensus": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://mcp.consensus.app/mcp"]
}
}
}
```
Add to your MCP configuration:
```json theme={null}
{
"servers": {
"consensus": {
"url": "https://mcp.consensus.app/mcp"
}
}
}
```
Add to your MCP configuration:
```json theme={null}
{
"mcpServers": {
"consensus": {
"serverUrl": "https://mcp.consensus.app/mcp"
}
}
}
```
Add Consensus as a custom app for Gemini Spark:
Go to [gemini.google.com](https://gemini.google.com) and sign in with a personal Google Account, then click **Settings & help** → **Connected Apps**.
Under **Custom apps for Spark**, click **Add a custom app** and paste the server URL:
```
https://mcp.consensus.app/mcp
```
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.
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.
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.
## 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.
Connect the Consensus app in ChatGPT using the steps above.
Start a Deep Research request in ChatGPT.
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](https://claude.ai/new?q=What%20does%20the%20research%20say%20about%20creatine%20and%20cognitive%20function%3F) · [ChatGPT](https://chatgpt.com/?q=What%20does%20the%20research%20say%20about%20creatine%20and%20cognitive%20function%3F) |
| "Find meta-analyses on mindfulness for anxiety published since 2020" | [Claude](https://claude.ai/new?q=Find%20meta-analyses%20on%20mindfulness%20for%20anxiety%20published%20since%202020) · [ChatGPT](https://chatgpt.com/?q=Find%20meta-analyses%20on%20mindfulness%20for%20anxiety%20published%20since%202020) |
| "Are there RCTs on intermittent fasting with more than 500 participants?" | [Claude](https://claude.ai/new?q=Are%20there%20RCTs%20on%20intermittent%20fasting%20with%20more%20than%20500%20participants%3F) · [ChatGPT](https://chatgpt.com/?q=Are%20there%20RCTs%20on%20intermittent%20fasting%20with%20more%20than%20500%20participants%3F) |
| "What is the strongest evidence for and against remote work productivity?" | [Claude](https://claude.ai/new?q=What%20is%20the%20strongest%20evidence%20for%20and%20against%20remote%20work%20productivity%3F) · [ChatGPT](https://chatgpt.com/?q=What%20is%20the%20strongest%20evidence%20for%20and%20against%20remote%20work%20productivity%3F) |
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](https://consensus.app/sign-up) or upgrade at [consensus.app/pricing](https://consensus.app/pricing).
## Enterprise and API Key Access
For enterprise access with unlimited rate limits, include your API key as a Bearer token:
```http theme={null}
Authorization: Bearer YOUR_API_KEY
```
Contact Consensus for enterprise API access at [consensus.app/home/api](https://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:
Array of paper objects with `title`, `authors`, `abstract`, `journal`, `year`, `citation_count`, and `url` (direct link to the paper on Consensus).
Total number of papers found.
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 thread tools
The Consensus MCP server exposes research-thread tools for multi-turn, agentic research. Use `create_thread` to start a new thread and `add_to_thread` to continue an existing thread with a new follow-up.
### `create_thread`
Creates a new research thread and dispatches the Consensus research agent. Use this for detailed, synthesis, comparison, or multi-step research questions. For a simple list of papers, prefer the `search` tool.
#### Parameters
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| input\_message | string | Yes | Your complete research brief. Include the full question, scope, constraints, and any ordered sub-tasks. |
| mode | string | No | Research depth. `pro` (default, fast) or `deep` (multi-step literature review, requires a signed-in paid caller). |
| filters | object | No | Optional structured filters. Supports the same keys as the Search Tool. |
| attachments | object | No | Optional attachments. `{"paper_attachments": [{"paper_id": "...", "es_hash_paper_id": "..."}], "collection_ids": [123]}`. |
### `add_to_thread`
Adds a new interaction to an existing research thread. Use this only for a genuinely new follow-up after seeing the previous interaction's results. Do not use it to decompose a single request across multiple calls — put the whole request in the `create_thread` brief instead.
#### Parameters
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| thread\_id | string | Yes | The `thread_id` returned by `create_thread`. |
| input\_message | string | Yes | A new follow-up question. The agent uses thread context and can reference papers from earlier turns. |
| mode | string | No | Research depth. `pro` (default) or `deep` (requires a signed-in paid caller). |
| title | string | No | The thread title from the `create_thread` response. Used only for the deep-link label; if omitted, the URL uses an `untitled` slug. |
| filters | object | No | Optional structured filters. Supports the same keys as `create_thread`. |
| attachments | object | No | Optional attachments. Same shape as `create_thread`. |
### Dispatch response
Both tools return an immediate dispatch confirmation while the agent runs asynchronously.
The thread identifier.
The new interaction identifier.
The thread title used in the deep-link label.
`running` while the agent is working.
`pro` or `deep`.
Direct link to view the thread in Consensus.
Human-readable confirmation with the Consensus link.
Whether the result should be displayed first.
Minimum seconds to wait before polling for completion (30).
Maximum recommended wait time: 180 seconds for `pro`, 600 seconds for `deep`.
Polling instructions for the model.
`deep` mode requires a signed-in paid Consensus account. Free accounts that request `deep` will receive a paid-account error.
## Troubleshooting
You added the server with `-- --transport http` instead of `--url`. Remove and re-add:
```bash theme={null}
codex mcp remove consensus
codex mcp add consensus --url https://mcp.consensus.app/mcp
codex mcp login consensus
```
Fully quit and restart Claude Code. Do not just use the reconnect option. Your credentials are saved and will work after restart.
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
* Verify the URL includes `/mcp` at the end
* Remove and re-add the server using the commands above
* Restart your client completely
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.
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.
Try broadening your search query or removing filters. Use specific academic terminology rather than casual language.
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.
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
Explore the Consensus research platform.
Full reference for the Consensus search API.
Learn more about the Model Context Protocol.
View the source, report issues, and star the Consensus MCP server.