openevidence-skill

An agent skill for installing, managing, and using the canonical OpenEvidence MCP.

OpenEvidence blocks plain server-side API requests with bot detection. This skill therefore does not contain an API client. It sets up and guides the working MCP architecture: requests run inside your own logged-in Chromium tab through the upstream browser extension and a localhost relay.

Architecture

AI client
   │  MCP tools such as oe_ask
   ▼
openevidence-mcp ──► shared relay daemon ──► Chromium extension ──► logged-in
  stdio server          127.0.0.1:8787         in-tab fetch          OE tab

• Your browser login is the default authentication path.
• The relay listens on localhost and is shared by concurrent MCP sessions.
• The extension runs requests from the real browser context, including its origin, cookies, and TLS fingerprint.
• This skill stays thin: all server, extension, protocol, and API behavior remains upstream.

Requirements

• Node.js 22 or newer
• Git and Make
• A Chromium-based browser: Chrome, Edge, Brave, Arc, Vivaldi, or Opera
• A supported MCP client such as Codex CLI or Claude Code
• An OpenEvidence account you are authorized to use

Install the skill

npx skills add htlin222/openevidence-skill
# or install globally
npx skills add -g htlin222/openevidence-skill

Then ask your agent:

Use $openevidence to install OpenEvidence MCP.

The skill's scripts/oe-mcp.sh install wrapper clones the upstream repository to ~/openevidence-mcp by default, then delegates dependency installation, builds, and MCP registration to upstream make all. Set OE_MCP_DIR=/absolute/path before running it to choose another checkout location.

You may also run the wrapper directly from the installed skill directory:

bash scripts/oe-mcp.sh install

Complete the browser setup

After the automated install, complete this one manual step:

1. Open chrome://extensions in your Chromium browser.
2. Enable Developer mode.
3. Select Load unpacked and choose ~/openevidence-mcp/extension/dist (or $OE_MCP_DIR/extension/dist).
4. Stay logged in to openevidence.com in that browser.
5. Reconnect or restart your MCP client.

Verify the pipeline with oe_health, then verify the browser login with oe_auth_status. These are intentionally different: health is a fast local relay check, while auth performs a full OpenEvidence network round trip.

Ask a question

Mention OpenEvidence in your prompt so the agent selects the MCP tools:

Use OpenEvidence to review current evidence for SGLT2 inhibitors in HFpEF.
Preserve citations and include BibTeX.

The normal sequence is:

1. oe_ask submits the question and immediately returns a pending article_id.
2. oe_article_get retrieves the result; it can wait for completion when requested.

This fire-and-forget flow frees the shared browser tab for other sessions. Follow-up questions pass the previous article ID as original_article_id. The MCP can also search locally stored answers, read /ask/ links, manage collections, and save citation artifacts. See references/tools.md for all 19 current tools and selection guidance.

OpenEvidence output is clinical evidence support, not a substitute for professional judgment, patient-specific evaluation, or emergency care.

Manage the MCP

bash scripts/oe-mcp.sh status
bash scripts/oe-mcp.sh update
bash scripts/oe-mcp.sh cleanup
bash scripts/oe-mcp.sh uninstall

• update rebuilds and re-registers the server. Reload the browser extension and reconnect the MCP client afterward.
• cleanup removes orphan relay processes and stale temporary state while keeping the install and database.
• uninstall unregisters clients, stops daemons, and removes generated builds. It intentionally keeps user data under ~/.openevidence-mcp and leaves the browser extension installed.

The wrapper never sends an OpenEvidence request itself; it only invokes canonical upstream Make targets.

Privacy and sharing

The MCP's oe_article_set_access tool can make an owned conversation readable by anyone with its link. Use it only on explicit request. Never publish PHI, patient identifiers, medically sensitive details, credentials, or content that has not been reviewed for disclosure. Keep conversations private when uncertain.

Troubleshooting

• MCP tools are missing: finish installation, then reconnect or restart the MCP client.
• oe_health reports daemon down: invoke an MCP tool to auto-start it, or run scripts/oe-mcp.sh status; update/rebuild if the installed versions differ.
• Daemon is up but extension is disconnected: load or reload the unpacked extension and keep the Chromium browser running.
• oe_auth_status fails: sign in to OpenEvidence in the same browser that has the extension.
• After an update: reload “OpenEvidence MCP Relay” from chrome://extensions, then reconnect the client.
• Multiple browsers have the extension: keep it active in only one logged-in browser to avoid request races.

Exported cookies are not required for the default relay workflow. They remain an upstream legacy/auxiliary option for specialized tooling only.

License

Apache License 2.0. The MCP implementation is maintained separately in htlin222/openevidence-mcp and remains the canonical source.