---

Why this exists. Connecting an AI agent to enterprise data is easy. Connecting it safely is the hard part — and the part regulated organizations actually pay for. The risk is not the model; it is an agent with an open execute_query(sql) hatch over patient data. This server is the opposite: a small set of named, typed, least-privilege tools, every call validated against a policy and written to an append-only audit log. The agent can only do what the server deliberately exposes — nothing more.

This is the agent-facing front door to the Clinical RAG Engine. Where the RAG engine answers natural-language questions, this MCP server lets an autonomous agent decide when and how to query it — under strict, auditable constraints.

Data disclaimer. All clinical records are 100% synthetic, generated with scripts/generate_synthetic_data.py. No real patient data is present, referenced, or required.

---

What an agent can (and cannot) do

The agent never sends raw SQL or free text identifiers. It calls capabilities, not queries.

Tool	Validated input	Returns	Guardrail
search_clinical_notes	query: str, limit: int ≤ 10	grounded answer + cited snippets	delegates to the RAG engine; citations capped
get_patient_summary	patient_pseudo_id matching PT-\d{4}	age, sex, diagnosis, therapy	pseudo-IDs only; never returns the free-text note
aggregate_diagnoses	top_n: int ≤ 20	counts per diagnosis	aggregation only, no row-level export

Every call passes through the policy layer before execution and is appended to the audit log (ts / tool / params / row_count).

---

Architecture

   ┌──────────────┐      MCP (stdio / HTTP)      ┌──────────────────────────────┐
   │   AI Agent    │  ───────────────────────▶   │      Clinical MCP Server       │
   │ (Claude       │                              │                                │
   │  Desktop,     │  ◀───── tool results ─────   │  ┌──────────────────────────┐ │
   │  Cursor, ...) │                              │  │  TOOL REGISTRY (allow-list)│ │
   └──────────────┘                               │  │  • search_clinical_notes  │ │
                                                   │  │  • get_patient_summary    │ │
                                                   │  │  • aggregate_diagnoses    │ │
                                                   │  └────────────┬─────────────┘ │
                                                   │               ▼                │
                                                   │  ┌──────────────────────────┐ │
                                                   │  │  POLICY + AUDIT LAYER      │ │
                                                   │  │  • typed param validation  │ │
                                                   │  │  • pseudo-ID enforcement    │ │
                                                   │  │  • append-only audit log    │ │
                                                   │  └────────────┬─────────────┘ │
                                                   └───────────────┼────────────────┘
                                                                   ▼
                                       ┌──────────────────────────────────────────┐
                                       │  READ-ONLY data access                     │
                                       │  • semantic search → Clinical RAG Engine    │
                                       │  • structured view → local JSON snapshot    │
                                       └──────────────────────────────────────────┘

Key principle: least privilege by construction. Three narrow tools beat one powerful one. There is no generic query escape hatch anywhere in the codebase.

---

Tech Stack

Layer	Technology	Notes
Language	Python 3.11+	Type-hinted, ruff-clean.
Protocol	Model Context Protocol	Official mcp Python SDK (FastMCP).
Transport	stdio + streamable HTTP	stdio for local agents, HTTP for remote.
Semantic search	Clinical RAG Engine	Reached over HTTP — services stay decoupled.
Structured data	local JSON view	Read-only; no write/update/delete path.
Validation	Pydantic	Typed tool schemas and models.
Governance	policy + audit modules	Allow-listed tools, capped limits, audit trail.

---

Quickstart

Prerequisite: Python 3.11+. The semantic-search tool also needs the companion Clinical RAG Engine running; the structured tools work standalone.

# 1. Clone and enter
git clone https://github.com/dianapopovici/clinical-mcp-server.git
cd clinical-mcp-server

# 2. Environment
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install -e .    # install the clinical_mcp package itself (src/ layout)

# 3. Generate the synthetic read-only data view
python scripts/generate_synthetic_data.py --records 200

# 4a. Run over stdio (for local agents like Claude Desktop)
python -m clinical_mcp --transport stdio

# 4b. Or run over HTTP (for remote agents)
python -m clinical_mcp --transport http

Windows note: there is no make here — run the commands above directly.

---

Connect it to Claude Desktop

Add this to your Claude Desktop claude_desktop_config.json (an example lives in examples/claude_desktop_config.json):

{
  "mcpServers": {
    "clinical": {
      "command": "python",
      "args": ["-m", "clinical_mcp", "--transport", "stdio"],
      "cwd": "/absolute/path/to/clinical-mcp-server"
    }
  }
}

Restart Claude Desktop and the three clinical tools become available to the agent.

---

Governance, concretely

• Least privilege. An agent literally cannot request a capability the server does not expose. No execute_query, no raw note dumps, no real identifiers.
• Policy before execution. Limits are capped (≤ 10, ≤ 20); patient lookups must match PT-\d{4}; violations are rejected with a clear message and nothing is touched.
• Auditability. Every call appends one JSON line to audit.log — ts / tool / params / row_count. In a regulated setting, that trail is a feature, not an afterthought.
• Decoupling. Semantic search is delegated to the RAG engine over HTTP. Swap either side freely; the contract is the protocol, not a vendor.

---

Project Structure

clinical-mcp-server/
├── src/clinical_mcp/
│   ├── __main__.py        # CLI: python -m clinical_mcp --transport {stdio,http}
│   ├── server.py          # FastMCP server + the 3 governed tools
│   ├── policy.py          # validation guardrails (the governance core)
│   ├── audit.py           # append-only audit trail
│   ├── data_access.py     # read-only local data view
│   ├── rag_client.py      # HTTP client for the Clinical RAG Engine
│   ├── config.py          # 12-factor settings
│   └── models.py          # Pydantic models
├── scripts/
│   └── generate_synthetic_data.py
├── tests/                 # deterministic units for policy / audit / data
├── examples/
│   └── claude_desktop_config.json
├── DECISIONS.md           # why it is built this way
└── requirements.txt

See DECISIONS.md for the engineering rationale behind every major choice.

---

Roadmap

• OAuth-scoped HTTP transport for multi-tenant deployments.
• Per-tool rate limiting + token-budget enforcement.
• Tamper-evident (signed) audit log.

---