# Getting Started with the Consensus MCP The Consensus MCP server enables AI assistants like ChatGPT, Claude, and other MCP-compatible clients to search over 200 million peer-reviewed academic research papers directly from the conversation. ## Getting Started Consensus MCP lets AI assistants search 200+ 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` > > The `/mcp` path is required. Using `https://mcp.consensus.app` alone will not work. *** ## Connect Your Client ### Claude Desktop 1. Go to **Settings → Connectors** 2. Click **Browse Connectors** 3. Search for **Consensus** 4. Click **Connect** — OAuth sign-in will open automatically ### ChatGPT 1. Click **Apps** from the left sidebar 2. Search for **Consensus** 3. Click **Connect** and sign in with your Consensus account Search results display in an interactive widget showing top papers with citations and direct links. Consensus also works with **ChatGPT Deep Research**. When Deep Research uses the Consensus app, it can search Consensus for relevant papers and fetch full paper details for cited results. #### Using Consensus with ChatGPT Deep Research 1. Connect the Consensus app in ChatGPT using the steps above 2. Start a **Deep Research** request in ChatGPT 3. 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, fetch paper details, and return a cited synthesis with direct links to papers on Consensus. The `fetch` tool used by Deep Research is currently available for ChatGPT only. Other MCP clients use the `search` tool. ### Claude Code ```bash 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. ### Codex ```bash codex mcp add consensus --url https://mcp.consensus.app/mcp codex mcp login consensus ``` ### Cursor Add via **Settings → Tools & MCP → New MCP Server**, or edit your config directly: ```json { "mcpServers": { "Consensus": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://mcp.consensus.app/mcp" ] } } } ``` ### VS Code (GitHub Copilot) Add to your MCP configuration: ```json { "servers": { "Consensus": { "url": "https://mcp.consensus.app/mcp" } }, "inputs": [] } ``` In the text box click the '+' button -> Tools... -> Select the `search` tool call from the Consensus MCP. ### Windsurf Add via **Settings → Cascade → MCP Servers**, or edit your config directly: ```json { "mcpServers": { "consensus": { "serverUrl": "https://mcp.consensus.app/mcp" } } } ``` ### Other MCP Clients Any MCP compatible client can connect using the server URL `https://mcp.consensus.app/mcp` with HTTP transport. If your client supports OAuth, authentication will be handled automatically. *** ## Verify Your Connection Try asking your AI assistant: > What does the research say about the effects of exercise on depression? You should see results citing specific papers with titles, journals, years, citation counts, and direct links. For ChatGPT Deep Research, try: > Use Consensus to do deep research on the effects of exercise on depression. Focus on human studies, systematic reviews, meta-analyses, and randomized controlled trials. *** ## 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 | Papers per Search | Monthly Searches | Extra Features | | ---------- | ----------------- | ---------------- | ------------------------- | | No Account | 3 | Unlimited | — | | Free | 10 | 30 | Full abstracts | | Pro | 20 | 250 | Study type, key takeaways | | Deep | 20 | 1,000 | Study type, key takeaways | | Teams | 20 | 1,000 | Study type, key takeaways | 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: ``` 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. | | `human` | boolean | No | Set to `true` to include only studies involving human subjects. | | `sample_size_min` | integer | No | Exclude studies with sample sizes smaller 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. | | `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. | ### Response Each search returns: * **papers** — Array of paper objects with: `title`, `authors`, `abstract`, `journal`, `year`, `citation_count`, and `url` (direct link to the paper on Consensus) * **total\_results** — Total number of papers found * **query** — 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" *** ## Fetch Tool The `fetch` tool retrieves full paper details for a specific paper found by `search`. This tool is currently available for **ChatGPT only** and is used by **ChatGPT Deep Research** to retrieve paper details after search results are found. Users usually do not need to call `fetch` directly. ### Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Yes | Exact paper ID from a Consensus search result. This is the 32-character ID in Consensus paper URLs such as `/papers/details/{id}/`. | ### Response Each fetch returns a single paper object with: * **id** — Consensus paper ID * **title** — Paper title * **text** — Abstract and available paper details for citation * **url** — Direct link to the paper on Consensus * **metadata** — Authors, journal, publication year, citation count, and other available citation metadata Pro plans and above may include key takeaways when available. Enterprise may include DOI metadata when available. *** ## 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: ```bash 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 1. Verify the URL includes `/mcp` at the end 2. Remove and re-add the server using the commands above 3. 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. ### Fetch tool does not appear The `fetch` tool is currently available for ChatGPT only. Other MCP clients will only see the `search` tool. ### 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. ### 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 | | Other MCP Clients | Bearer token | Supported | *** ## Additional Resources * [Consensus Website](https://consensus.app) * [Consensus API Documentation](https://docs.consensus.app) * [Model Context Protocol Specification](https://modelcontextprotocol.io/)