Openevidence

OpenEvidence MCP

Use the canonical 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 when choosing among the complete tool set.

Resolve the skill directory containing this SKILL.md, then invoke:

bash <skill-directory>/scripts/oe-mcp.sh <install|update|status|cleanup|uninstall>

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 <openevidence-mcp>/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/<id> 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/<id> 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.