MedCP docs

Connect an MCP host to MedCP.

Start with SPOKE only, add one OMOP backend when you need clinical evidence, and validate the path with aggregate queries before using institution-approved data.

Choose an integration Agent setup file

01 · Start here

Install from source

The current source tree is version 0.10.0. Its matching Git tag is not yet published, so tag-based uvx commands are not presented as working installs here. uv sync --locked uses the committed dependency lock. SPOKE-only use needs no database credentials.

Terminal

git clone https://github.com/BaranziniLab/MedCP.git
cd MedCP
uv sync --locked
uv run --locked medcp

What starts by default

The bundled read-only SPOKE connection. Leave every CLINICAL_RECORDS_* variable unset for knowledge-graph-only use.

02 · Compatibility

Supported clients and backends

Path	Requirement	Current verification
Direct core	Python 3.11+ and uv	Python 3.11-3.13 on Linux, macOS, and Windows
BioRouter	BioRouter and uv	1.88.6 across SQLite, Amazon RDS for MySQL, Amazon RDS for SQL Server, and SPOKE
Codex CLI	Codex CLI with MCP support and uv	0.145.0 across the same release matrix
Claude Code	Claude Code 2.x+ and uv	Integration provided; not in the v0.10.0 verified host matrix
Claude Desktop	Claude Desktop with MCPB support	Current bundled runtime is macOS Apple silicon only

MedCP targets sessionless MCP 2026-07-28 and retains legacy initialization for hosts that have not moved to the modern lifecycle. Production transport is stdio only.

03 · Install

Pick a host

Select an integration for exact setup steps, package status, and the data-handling boundary that applies to that host.

Verified host

BioRouter

The canonical MedCP benchmark harness, with local orchestration and an OS-keyring path for values entered as secrets.

Needs: uv and an approved database path
Data boundary: Version 1.88.6 was verified. Values entered through its secret-setting flow can use the configured OS keyring. The full model and data path still needs institutional approval.

Get staged MedCP.brxt

Setup

biorouter extension install MedCP.brxt \
  --env CLINICAL_RECORDS_BACKEND=sqlite \
  --env CLINICAL_RECORDS_SQLITE_PATH=/absolute/path/database.sqlite

04 · Configure

Add one clinical backend

SQLite is the simplest test path. For MySQL or SQL Server, use a dedicated account with SELECT and no write-capable grants. Never give an agent-facing server an administrator credential.

Local SQLite

export CLINICAL_RECORDS_BACKEND=sqlite
export CLINICAL_RECORDS_SQLITE_PATH=/absolute/path/database.sqlite

Remote SQL

export CLINICAL_RECORDS_BACKEND=mysql  # or mssql
export CLINICAL_RECORDS_SERVER=db.example.org
export CLINICAL_RECORDS_DATABASE=omop
export CLINICAL_RECORDS_USERNAME=reader
export CLINICAL_RECORDS_PASSWORD='use-a-secret-store'

Variable	Purpose	Default
`CLINICAL_RECORDS_BACKEND`	sqlite, mysql, or mssql	No EHR backend
`CLINICAL_RECORDS_SQLITE_PATH`	Absolute path to a SQLite file	Unset
`CLINICAL_RECORDS_SERVER`	MySQL or SQL Server host	Unset
`CLINICAL_RECORDS_DATABASE`	Clinical database name	Unset
`CLINICAL_RECORDS_USERNAME`	Dedicated read-only account	Unset
`CLINICAL_RECORDS_PASSWORD`	Password for the read-only account	Unset
`CLINICAL_RECORDS_PORT`	Optional remote database port	Driver default
`MEDCP_DISABLE_KNOWLEDGE_GRAPH`	Set to 1 for EHR-only mode	0
`MEDCP_NAMESPACE`	Prefix used for MCP tool names	MedCP
`MEDCP_LOG_LEVEL`	DEBUG, INFO, WARNING, or ERROR	INFO

Set KNOWLEDGE_GRAPH_URI, username, password, and database only when replacing the bundled SPOKE connection with your own Neo4j graph.

05 · Use

Begin with a small aggregate query

Smoke-test prompt

Use only MedCP. List the clinical tables, count rows in the person table, and report the exact tool names and raw aggregate outputs. Do not return patient-level records.

DiscoverList tables or inspect the SPOKE schema.
QueryUse SELECT or read-only Cypher with a narrow result.
CheckReview the tool call and source result before interpretation.
ReportReturn aggregate evidence, limitations, and follow-up questions.

06 · Testing

Four different kinds of evidence

Core suite40 cases

Modern and legacy MCP, namespaces, read-only SQL, stdio purity, provisioning logic, and repository hygiene.

Cross-platform CI9 jobs

Python 3.11, 3.12, and 3.13 on Linux, macOS, and Windows.

Live backend gate3 SQL backends

One de-identified 100-patient MIMIC-IV OMOP demo in SQLite, Amazon RDS for MySQL, and Amazon RDS for SQL Server.

Clinical evaluation100 questions

Ten complexity tiers, two current models, and MedCP with SPOKE compared with MedCP EHR-only through BioRouter.

What the live backend gate proves

Load the same 32-table fixtureCreate a SELECT-only readerConfirm 100 peopleReject a DELETE statementCompare backend resultsQuery the live SPOKE graph

AWS test boundary

The scripts create disposable Amazon RDS database fixtures. The Amazon EC2 API is used only for VPC and security-group operations; the scripts do not create EC2 instances. These fixtures are compatibility tests, not a HIPAA-compliant deployment reference.

Research evaluations are separate

The clinical-question benchmark uses UCSF OMOP_DEID through BioRouter, not the AWS demo fixture. The reported benchmark contains 399 completed evaluations across GPT-5.5 and Claude Opus 4.8. BiomixQA separately evaluates 617 gene-disease items. Literature replication turns a published study into an auditable cohort, analysis, and comparison report.

Run the network-free suite

uv sync --locked
uv run --locked pytest tests

07 · Privacy and HIPAA

Approve the complete data path

MedCP alone does not establish HIPAA compliance. It runs locally over stdio, but databases may be remote and query results return to the host.

A private deployment can pair MedCP with BioRouter or another approved harness, a local or institution-hosted model, and on-premises data systems. Review the complete host, model, network, logging, retention, access-control, and contractual path.

Private deployment pattern

Keep the host, model, MedCP process, database endpoint, logs, and exports inside the institutional boundary. Enforce identity, role permissions, small-cell limits, disclosure budgets, and audit review in the surrounding environment.

Codex CLI, Claude Code, Claude Desktop

Use non-PHI or appropriately de-identified data unless your institution has approved the host, model provider, network, logging, retention, access controls, and contracts.

BioRouter

BioRouter can store values entered through its secret-setting flow in the configured OS keyring. In the evaluated benchmark harness, limited prompt-injection and PHI patterns were annotated for review, not blocked.

Every host

Read-only controls prevent mutation. They do not prevent disclosure of returned rows to the agent or model. Core MedCP does not enforce row limits, PHI redaction, or small-cell suppression.

Keep credentials out of prompts and commits. Codex CLI and Claude Code settings can be plaintext. Claude Desktop protects sensitive manifest fields. BioRouter can store secrets in its configured OS keyring.

08 · Downloads

Staged source-tree packages

All four v0.10.0 files pass the checked-in SHA-256 checksums. They are staged in the repository, but v0.10.0 is not yet a published Git tag or GitHub release. The Codex CLI and Claude Code packages still default to that missing tag, so use the source setup above for those two hosts.

BioRouterMedCP.brxtStaged package · checksum verified Claude DesktopMedCP.mcpbStaged package · macOS Apple silicon Codex CLImedcp-codex.zipStaged package · source setup recommended Claude Codemedcp-claude-code-plugin.zipStaged package · source plugin recommended

BioRouter website ↗Codex CLI documentation ↗Claude Code website ↗Claude Desktop download ↗Checksums and install notes ↗Published GitHub releases ↗

09 · License and legal

Open source research software

MedCP software is released under the MIT License. It is provided without warranty. It is research software only and is not for patient-care decisions.

The MIMIC-IV OMOP demo has separate provenance and license terms. Review the included dataset license and PhysioNet documentation before reuse.

Software license ↗Dataset provenance ↗