# MedEval MCP Server

Authenticated Streamable HTTP MCP access to a running [MedEval](https://xiaoyuu.me/) 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:

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

macOS/Linux:

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

### 2. Configure Codex

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

```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](https://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

```bash
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:

```bash
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/`](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:

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

Store it in a root-readable environment file:

```text
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

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

## License

MIT