MedEval MCP Server

Authenticated Streamable HTTP MCP access to a running MedEval medical-device regulatory workspace.

Public endpoint: https://xiaoyuu.me/mcp

The server exposes MedEval project selection, evidence retrieval, CEP/CER section context, Agent observability, generation/evaluation task control, and immutable document revisions to Codex-compatible MCP clients.

Security model

• Every MCP request requires Authorization: Bearer <token>.
• The MCP process binds to 127.0.0.1; only Nginx exposes it over HTTPS.
• The adapter may call only a loopback MedEval API.
• No delete, cleanup, cancel, rollback, or arbitrary server-file upload tool is exposed.
• The access token is stored only in /etc/medeval-mcp.env on the server and must never be committed.
• This deployment uses one shared MedEval instance. Anyone with the token can inspect its projects and invoke its exposed write tools. Use separate deployments/tokens when tenant isolation is required.

MedEval itself can still call model and literature providers configured by the server operator. Do not assume that those downstream operations are offline merely because the MCP adapter is private.

Use with Codex

Codex supports Streamable HTTP MCP servers with bearer tokens. Put the token in an environment variable rather than in config.toml.

1. Set the token

PowerShell:

$env:MEDEVAL_MCP_TOKEN = "the-token-provided-by-the-server-owner"

macOS/Linux:

export MEDEVAL_MCP_TOKEN='the-token-provided-by-the-server-owner'

2. Configure Codex

Add this to ~/.codex/config.toml:

[mcp_servers.medeval]
url = "https://xiaoyuu.me/mcp"
bearer_token_env_var = "MEDEVAL_MCP_TOKEN"
tool_timeout_sec = 1800
startup_timeout_sec = 30
default_tools_approval_mode = "writes"

Restart the ChatGPT desktop app, Codex CLI, or IDE extension. Use /mcp to verify that medeval is connected.

The writes approval mode lets read-only inspection run normally while prompting before generation, evaluation, workspace creation, or document patching.

Typical workflow

1. Call medeval_health.
2. Call medeval_list_projects; never guess a workspace or task ID.
3. Upload source materials through xiaoyuu.me when needed. Remote MCP deliberately cannot read paths on the client computer.
4. Use medeval_search_project_evidence or medeval_build_section_context for traceable retrieval.
5. Start generation/evaluation only after explicit authorization and retain the returned task ID.
6. Inspect medeval_get_task_progress, medeval_list_runs, and medeval_get_run rather than blindly resubmitting a slow task.
7. For edits, read the current revision, patch with its base_revision_id, then verify the resulting diff.

Product facts must come from uploaded product materials. External literature is supporting evidence and must not silently replace intended use, indications, specifications, risks, or test results.

Available tools

Read-only tools:

• medeval_health
• medeval_list_projects
• medeval_get_workspace
• medeval_list_workspace_documents
• medeval_list_runs
• medeval_get_run
• medeval_get_agent_context
• medeval_list_project_documents
• medeval_search_project_evidence
• medeval_build_section_context
• medeval_list_generation_templates
• medeval_get_task_progress
• medeval_get_generation_task
• medeval_list_document_revisions
• medeval_read_document_revision
• medeval_diff_document_revisions

Non-destructive write tools:

• medeval_create_workspace
• medeval_start_generation
• medeval_start_evaluation
• medeval_patch_document_revision

Run your own instance

Requirements:

• Python 3.11+
• A reachable MedEval FastAPI backend on the same host
• HTTPS reverse proxy for public use

git clone https://github.com/hanxiaoyu-cmd/medeval-mcp-server.git
cd medeval-mcp-server
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
cp .env.example .env

Export the variables from .env, then run:

python -m medeval_mcp_server

The default listener is 127.0.0.1:8765; the MCP route is /mcp and the public health route is /healthz.

Production deployment

Example systemd and Nginx files are under deploy/:

• medeval-mcp.service runs an unprivileged, hardened process.
• nginx-location.conf proxies /mcp without buffering and keeps long tool calls alive.

Generate a token with:

python -c 'import secrets; print(secrets.token_urlsafe(36))'

Store it in a root-readable environment file:

MEDEVAL_MCP_TOKEN=<generated-token>
MEDEVAL_API_BASE_URL=http://127.0.0.1:8000
MEDEVAL_MCP_PUBLIC_HOSTS=your-domain.example,127.0.0.1,localhost

Set the file mode to 600, validate Nginx with nginx -t, and verify both unauthenticated rejection and authenticated MCP initialization before sharing the token.

Development

python -m pip install -e ".[dev]"
python -m pytest
python -m compileall -q src

License

MIT