MedEval MCP (local)

Local-only Model Context Protocol gateway for the private MedEval medical-device regulatory workbench.

It lets an MCP client operate MedEval workspaces, canonicalized materials, evidence retrieval, CEP/CER generation and evaluation, workflow observability, and immutable document revisions. MedEval remains the system of record; this project is a thin, bounded adapter.

Safety boundary

• stdio transport only; no network MCP listener

• connects to loopback by default, with explicit opt-in for trusted private-network IPs

• explicit workspace/task identifiers

• allowlisted local upload roots

• no delete, shell, deployment, or secret-management tools

• asynchronous starts return task IDs and must be polled, not duplicated

• product facts cannot be derived from external literature

• document edits require the current base_revision_id

See SECURITY.md.

Requirements

• Windows or another Python 3.11+ environment

• MedEval running at http://127.0.0.1:8000

• Python package dependencies from pyproject.toml

Install

cd C:\path\to\medeval-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
Copy-Item .env.example .env

The MCP process reads normal environment variables. MCP clients generally supply them in their server configuration rather than loading .env automatically.

Configure

Minimum local configuration:

MEDEVAL_BASE_URL=http://127.0.0.1:8000
MEDEVAL_PROJECT_ROOT=C:\path\to\medeval
MEDEVAL_ALLOWED_FILE_ROOTS=C:\path\to\medeval;C:\path\to\materials

If MedEval enables MEDEVAL_API_TOKEN, give this MCP process the same MEDEVAL_API_TOKEN; it is sent as X-API-Token. A signed browser/session token can instead be supplied as MEDEVAL_BEARER_TOKEN.

macOS client to a trusted LAN backend

When MedEval is listening on another computer in the same trusted LAN, use its literal private IP and opt in explicitly:

MEDEVAL_BASE_URL=http://192.168.0.166:8001
MEDEVAL_ALLOW_PRIVATE_NETWORK=true
MEDEVAL_PROJECT_ROOT=/Users/your-name/MedEval
MEDEVAL_ALLOWED_FILE_ROOTS=/Users/your-name/MedEval:/Users/your-name/Documents

The MCP remains a local stdio process on the Mac. Public IP addresses and domain names are still rejected.

Connect from Codex

Use examples/codex.mcp.json as the MCP server definition. The command must point to this project's .venv Python and use:

-m medeval_mcp.server

Restart Codex after changing the MCP configuration, then ask it to call medeval_health.

Run manually

MCP stdio uses standard output for protocol messages, so a manual run appears idle:

.\.venv\Scripts\python.exe -m medeval_mcp.server

Use an MCP client or Inspector to interact with it.

The bundled local launcher sets the loopback backend and upload roots before starting stdio:

.\scripts\run_local.ps1

Protocol and backend smoke test:

.\.venv\Scripts\python.exe scripts\mcp_smoke.py --health

Tool surface

The first release provides 21 tools:

• workspace: health, project list, create/get workspace, workspace documents

• observability: run list, run detail, bounded agent context

• evidence: project documents, evidence search, section context

• ingestion: allowlisted local material upload and canonicalization

• generation: template list, start generation, generation/task status

• evaluation: start evaluation

• revisions: list, bounded read, diff, optimistic-lock patch

medeval_start_generation defaults to tag_index_agent, which uses MedEval's dependency-serial segmented writer. Full-context strategies remain opt-in.

Tests

.\.venv\Scripts\python.exe -m pytest

The tests use mock HTTP transports and do not start LLM generation or consume model quota. A separate integration smoke test lists MCP tools and calls the already-running local /api/health endpoint.

Not included yet

• remote Streamable HTTP transport

• xiaoyuu.me deployment

• multi-user API keys and workspace ownership

• remote upload staging

• destructive project/task deletion