medeval-mcp
This server is a local, read/write MCP gateway for the private MedEval regulatory workbench, offering workspace management, evidence retrieval, CEP/CER generation, evaluation, observability, and immutable document revision tools.
Check backend health and capability summary
List/create/read workspaces and list workspace documents
Observe workflow runs, run details, and bounded agent context
List project evidence documents, search local evidence, and build section-scoped evidence packs
Ingest allowlisted local materials into cleaning sessions
List generation templates, start normal or researched generation, and poll generation progress
Start evaluations and poll task progress
List, read, diff, and patch immutable document revisions with optimistic locking
All actions are scoped to explicit workspace/task identifiers and enforce safety boundaries (no delete, shell, deployment, or secret-management tools)
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@medeval-mcp search clinical evidence for the new stent"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Related MCP server: ResearchBrain MCP Server
Requirements
Windows or another Python 3.11+ environment
MedEval running at
http://127.0.0.1:8000Python 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 .envThe 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\materialsIf 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/DocumentsThe 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.serverRestart Codex after changing the MCP configuration, then ask it to call medeval_health.
Bundled Codex plugin and Skill
This repository is also a Codex plugin package. The manifest at
.codex-plugin/plugin.json binds the local MCP server to the
skills/medeval-regulatory Skill, so a GitHub checkout contains both the tool
implementation and the model-facing workflow guidance.
The bundled .mcp.json uses python3, the repository root as its working
directory, and ./src as PYTHONPATH. Install this project's Python
dependencies into the interpreter Codex launches before enabling the plugin.
If the local interpreter has a different command or virtual-environment path,
override the MCP command in the local Codex configuration.
The Skill contains generation safeguards that are intentionally more specific than the low-level API defaults:
create a typed
GenerationContractbefore choosing a template;preserve zero-file product statements as provisional
USER_ASSERTEDfacts;require explicit, exactly matching
template_idsandgeneration_strategy;use a concise
regulatory_research_memofor a scoped question instead of silently expanding it into a CEP/CER;bind structured research modes and SourceRefs to contract claim IDs;
distinguish execution completion from quality approval and release readiness;
submit asynchronous work once, retain the task ID, and inspect status instead of resubmitting.
For the root-cause map, before/after architecture, contracts, tests, backend
requirements, and migration notes, see
docs/current-mcp-analysis-handoff.md.
Run manually
MCP stdio uses standard output for protocol messages, so a manual run appears idle:
.\.venv\Scripts\python.exe -m medeval_mcp.serverUse 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.ps1Protocol and backend smoke test:
.\.venv\Scripts\python.exe scripts\mcp_smoke.py --healthTool surface
The local gateway provides 35 tools:
workspace: health, project list, create/get workspace, instruction-only sessions, workspace documents, and typed user assertions
observability: run list, run detail, bounded agent context
contracts: freeze/read
GenerationContractand run deterministic preflightevidence: project documents, evidence search, section context, typed device relationships, and time-bounded regulatory status
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 has no template or strategy default. The caller must
pass a non-empty template list, an explicit strategy, and the exact frozen
contract. Mismatches fail preflight before model work begins.
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:
build or accept bounded, claim-bound research queries with explicit modes;
execute up to four queries concurrently through MedEval's configured search;
extract bounded source text and store immutable SourceRefs plus structured research receipts in the selected Agent workspace;
freeze the workspace version and integrity hash;
run the claim-by-source and consistency preflight;
create exactly one generation task only when preflight passes.
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.
An execution terminal state is not release approval. A Word deliverable is
available only when deterministic validation, independent review, and rendered
page QA pass and the status reports release_ready=true.
After a task produces a releasable 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 pytestThe 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.medeploymentmulti-user API keys and workspace ownership
remote upload staging
destructive project/task deletion
Available Tools
21 toolsmedeval_build_section_contextBRead-onlyIdempotent
Build a bounded, section-scoped evidence pack for one CEP/CER section.
Inputs: project_id (required), section_id (required), query, top_k, +1 more. Returns: object
medeval_create_workspaceA
Create an isolated workspace only after an explicit user request.
Inputs: title (required), metadata, workspace_id. Returns: object
medeval_diff_document_revisionsARead-onlyIdempotent
Compare two immutable revisions with a bounded textual diff.
Inputs: document_id (required), workspace_id (required), to_revision_id (required), from_revision_id (required), +1 more. Returns: object
medeval_get_agent_contextCRead-onlyIdempotent
Read the bounded context receipt for one agent in a selected run.
Inputs: run_id (required), agent_id (required), workspace_id (required). Returns: object
medeval_get_generation_taskBRead-onlyIdempotent
Read generation progress, output metadata, and adopted artifacts.
Inputs: task_id (required). Returns: object
medeval_get_runCRead-onlyIdempotent
Read agents, actions, retrievals, warnings, and outputs for one run.
Inputs: run_id (required), workspace_id (required). Returns: object
medeval_get_task_progressBRead-onlyIdempotent
Read a lightweight live status snapshot without resubmitting the task.
Inputs: task_id (required). Returns: object
medeval_get_workspaceBRead-onlyIdempotent
Read a selected workspace summary and integrity counters.
Inputs: workspace_id (required). Returns: object
medeval_healthARead-onlyIdempotent
Check the local backend and return a bounded capability summary.
Inputs: no named parameters. Returns: object
medeval_ingest_materialsB
Upload allowed local files into a new immutable cleaning session.
Inputs: file_paths (required), platform, device_hint, pdf_read_mode, +2 more. Returns: object
medeval_list_document_revisionsARead-onlyIdempotent
List immutable revisions and the current head for one document.
Inputs: document_id (required), workspace_id (required). Returns: object
medeval_list_generation_templatesARead-onlyIdempotent
List generation templates installed in the local MedEval backend.
Inputs: no named parameters. Returns: object
medeval_list_project_documentsBRead-onlyIdempotent
List raw and retrieved documents in one project evidence repository.
Inputs: project_id (required), limit. Returns: object
medeval_list_projectsBRead-onlyIdempotent
List local chat projects/workspaces; use before selecting a workspace.
Inputs: limit, query, cursor. Returns: object
medeval_list_runsBRead-onlyIdempotent
List observable workflow runs and agent progress for one workspace.
Inputs: workspace_id (required), limit. Returns: object
medeval_list_workspace_documentsARead-onlyIdempotent
List generated/versioned document heads in one workspace.
Inputs: workspace_id (required). Returns: object
medeval_patch_document_revisionB
Append one optimistic-lock revision; never overwrite revision history.
Inputs: operations (required), document_id (required), instruction (required), workspace_id (required), +1 more. Returns: object
medeval_read_document_revisionBRead-onlyIdempotent
Read a bounded page of one immutable Markdown revision.
Inputs: document_id (required), workspace_id (required), current, max_chars, +2 more. Returns: object
medeval_search_project_evidenceCRead-onlyIdempotent
Search bounded local evidence; inspect sources before factual use.
Inputs: query (required), project_id (required), top_k, node_type, +4 more. Returns: object
medeval_start_evaluationC
Start evaluation only after explicit authorization.
Inputs: platform (required), device_name (required), evidence, indication, +8 more. Returns: object
medeval_start_generationC
Start generation after explicit authorization; segmented generation is the safe default.
Inputs: clean_session_id (required), profile, template_ids, search_sources, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Tools generally have distinct purposes, but there is some overlap between get_run, get_task_progress, and get_generation_task, which could confuse an agent. Descriptions help clarify, but the boundaries are not perfectly crisp.
All tools share the 'medeval_' prefix and use a consistent snake_case verb_noun pattern (e.g., list_projects, create_workspace, read_document_revision). The one exception, medeval_health, is a minor deviation but does not break overall consistency.
21 tools is slightly heavy but justified given the broad domain covering workspaces, projects, evidence, generation, evaluation, and revisions. The count is within a reasonable range for such a server.
The tool surface covers most core workflows, but there are notable gaps: no workspace update/delete, no get_project, and no cancel/stop operations for generation or evaluation. These are gaps an agent might hit, though the main paths are present.
Maintenance
Related MCP Connectors
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Governed MCP gateway for business apps: roles, previews, approvals and one audit log.
Query, browse, and automate OmegaAI workspaces from any MCP client. Streamable HTTP with OAuth 2.0.
Managed MCP gateway with OAuth, per-agent permissions, shared accounts and activity logs.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables local MCP clients to interact with an AuroraCloud workspace, supporting object listing, content reading, search, and task management through authenticated API calls.44 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to interact with a local-first research knowledge workbench, supporting literature search, evidence-grounded Q&A, and reference export.2AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceProvides authenticated Streamable HTTP MCP access to a MedEval medical-device regulatory workspace, enabling project selection, evidence retrieval, section context, document revision management, and generation/evaluation task control.MIT
- FlicenseNot gradedqualityAmaintenanceEnables MCP-compatible clients and LLM agents to perform full CRUD operations on FHIR resources, query and manipulate clinical data through natural-language prompts, and use document ingestion, semantic search, and terminology lookup against a FHIR backend.-