Medeval

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 local gateway provides 27 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
• research: regulatory/literature query planning, workspace-scoped external search, bounded source-text extraction, and frozen generation context
• generation: template list, normal start, researched start, generation/task status, and opt-in post-generation information completion
• 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.

search_sources on the low-level generation tool is compatibility metadata; it does not itself run a search. For a CEP/CER that needs external evidence, use medeval_start_researched_generation. It performs this closed loop:

1. build or accept bounded research queries;
2. execute MedEval's configured Euris-first search with OpenSearch/AnySearch fallbacks;
3. extract bounded source text and store immutable SourceRefs plus research receipts in the selected Agent workspace;
4. freeze that workspace version and integrity hash into the generation request;
5. start the normal MedEval generation pipeline.

External material is always tagged external_reference; it may support SOTA, regulatory, clinical-background, comparison, and published-evidence statements, but cannot prove facts about the current device.

After a task produces a deliverable, medeval_complete_generation_gaps can run the existing corpus completion and explicitly opt into online collection. It writes a separate *_completed document and report, never overwriting the approved deliverable. Poll it with medeval_get_generation_completion.

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