# Openevidence > Install, manage, troubleshoot, and use the canonical openevidence-mcp server. Use when the user asks to set up or update OpenEvidence MCP, check its relay or login, query OpenEvidence for clinical evidence with citations or BibTeX, retrieve an OE answer or shared conversation, search prior answers, manage collections, or change conversation sharing. - Skill: `htlin222/openevidence` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add htlin222/openevidence` - Raw SKILL.md: https://api.skillmd.com/api/skills/htlin222/openevidence/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: htlin222 (https://skillmd.com/u/htlin222) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/htlin222/openevidence --- # OpenEvidence MCP Use the canonical [`htlin222/openevidence-mcp`](https://github.com/htlin222/openevidence-mcp) implementation. It sends OpenEvidence requests through a localhost relay and a Chromium extension running inside the user's logged-in browser tab. Never reimplement the OpenEvidence API, send direct HTTP requests to its private API, or fall back to an exported-cookie Python client. Plain server requests are blocked by bot detection. If the MCP tools are unavailable, install or repair the MCP instead. ## Route the request 1. If the user wants to install, update, inspect, clean up, or uninstall the MCP, run the matching command from `scripts/oe-mcp.sh`. 2. If the user wants OpenEvidence data and the `oe_*` MCP tools are available, call those tools directly. 3. If the user wants OpenEvidence data but the tools are unavailable, do not substitute a direct HTTP client. Install the MCP only when the user asked for setup or authorizes the prerequisite; otherwise explain the missing dependency and ask them to approve installation. Complete the manual browser step and reconnect the MCP client before attempting the query. 4. Read [`references/tools.md`](references/tools.md) when choosing among the complete tool set. Resolve the skill directory containing this `SKILL.md`, then invoke: ```bash bash /scripts/oe-mcp.sh ``` Honor `OE_MCP_DIR` when the user wants the upstream checkout in a non-default location. The default is `~/openevidence-mcp`. ## Install and connect For first-time setup, run `scripts/oe-mcp.sh install`. The wrapper checks Node.js 22+, clones the canonical repository if necessary, and delegates the build, extension, and MCP-client registration to upstream `make all`. Then instruct the user to complete the browser action that cannot be automated: 1. Open `chrome://extensions` in Chrome, Edge, Brave, Arc, Vivaldi, or Opera. 2. Enable **Developer mode**. 3. Choose **Load unpacked** and select `/extension/dist`. 4. Stay logged in to `https://www.openevidence.com` in that browser. 5. Reconnect or restart the MCP client so it discovers the newly registered server. Do not claim setup is complete before the extension is loaded and the client is reconnected. ## Verify health and authentication Use the two checks for different questions: - Call `oe_health` first to test the local pipeline. It checks the relay daemon, extension connection, protocol version, and recent activity without contacting OpenEvidence. - Call `oe_auth_status` only after health succeeds to verify that the browser tab is actually logged in. This performs a network round trip to `/api/auth/me` through the relay. If `oe_health` says the daemon is down, trigger an MCP call or run the status command and follow its hint. If the daemon is up but the extension is disconnected, ask the user to load/reload the extension and keep the Chromium browser running. If `oe_auth_status` fails, ask the user to sign in to OpenEvidence in that same browser. ## Ask and retrieve For a new clinical question: 1. Call `oe_health` when connection state is unknown. 2. Call `oe_auth_status` when login state is unknown or health alone is insufficient. 3. Call `oe_ask` with the user's question. Keep the default fire-and-forget behavior unless the user explicitly needs a blocking one-shot call. 4. Capture the returned `article_id` and pending status. 5. Call `oe_article_get` with that ID. Use `wait_for_completion: true` when the current turn should wait for the finished answer; otherwise fetch it later. 6. Present the OpenEvidence answer as sourced clinical evidence, preserve its citations, and distinguish it from independent medical advice. To continue a thread, pass the prior article ID or `/ask/` URL as `original_article_id` to `oe_ask`. Prefer `oe_answers_search` before spending another question when an earlier fetched answer may already cover the topic. ## Read links, share, and protect sensitive data Use `oe_public_get` for an OpenEvidence `/ask/` link when the user wants readable question-and-answer turns. Public links can work anonymously; private links require the connected logged-in relay session. Treat `oe_article_set_access` as a consequential write: - Change access only when the user explicitly asks. - Never make a conversation public if it contains PHI, patient identifiers, medically sensitive details, secrets, or content the user has not reviewed for disclosure. - State that `public: true` makes the link readable by anyone who has it. - When there is any doubt, keep the conversation private and ask the user to remove sensitive content or confirm the disclosure. Use collection create/add/bulk-apply tools only when the user asks to change organization. Prefer read-only list, get, summary, search, and unsorted tools for inspection. ## Manage the installation - `install`: clone if needed, build the server and extension, and register supported MCP clients. - `update`: fast-forward the upstream checkout, rebuild, and re-register. Then require the user to reload the extension and reconnect the client. - `status`: show upstream versions, relay health, and client registration. - `cleanup`: reap orphan relay processes and stale temporary state while keeping the installation and user database. - `uninstall`: unregister clients, stop daemons, and remove generated builds. It intentionally keeps `~/.openevidence-mcp` data and the browser extension. Do not delete the retained database or remove the browser extension unless the user separately and explicitly requests a full wipe. ## Boundaries - Keep the MCP server and extension implementation in the upstream repository; this skill is only an orchestration and usage layer. - Do not copy upstream TypeScript, extension code, protocol code, or API payload logic into this skill. - Do not use `cookies.json` as the primary setup. The logged-in browser extension is the default authentication path. - If install/update output asks for an extension reload or MCP reconnect, repeat that requirement clearly to the user.