🩺 family-health-mcp

The model can read everything it is allowed to see — and write exactly one thing.

An MCP server that connects a hosted LLM client to a local, file-based health archive, without ever handing the model write access to the archive itself.

Why

My family's health records live in plain files on one machine — an archive that a local agent and I curate together, and that part already worked well. The problem was everywhere else — at a clinic, on a phone, away from the machine holding the files. I could already reach it by SSH, so capability was never the issue; the issue was that every conversation had to start with connecting, and that small ritual is enough to make you skip it.

So instead of a better way to reach the archive, put the archive inside the app that is already open. Which leaves one question worth answering carefully: how much authority should a hosted model have over medical records?

Related MCP server: atlas_mcp

Architecture

flowchart TB
    C["💬 <b>ChatGPT</b><br/><i>developer-mode MCP client</i>"]
    T["☁️ <b>Cloudflare Tunnel</b><br/><i>outbound only · no open ports</i>"]

    subgraph SRV["🖥️ &nbsp;this server &nbsp;·&nbsp; 127.0.0.1:8787"]
        direction TB
        G1["🔑 <b>① random path</b> &nbsp;/mcp-&lt;token&gt;"]
        G2["🛡️ <b>② bearer token</b> &nbsp;constant-time compare"]
        G3["🧰 <b>③ tool surface</b> &nbsp;3 read · 1 write"]
        G1 --> G2 --> G3
    end

    subgraph ARC["📁 &nbsp;health archive &nbsp;·&nbsp; plain files"]
        direction TB
        REC["📚 <b>structured record</b><br/>history · medication · timeline · measurements"]
        INB["📥 <b>inbox</b><br/><i>the only writable path</i>"]
    end

    LOC["🏠 <b>local agent</b><br/><i>full read + write, under review</i>"]

    C -- HTTPS --> T --> G1
    G3 -- "read" --> REC
    G3 -- "create only" --> INB
    INB -. "reviewed &amp; filed" .-> REC
    LOC --> REC

    style SRV fill:#f6f8fa,stroke:#8b949e
    style ARC fill:#fff8e6,stroke:#d4a72c
    style INB fill:#ffeaa7,stroke:#d4a72c
    style C fill:#e8f0fe,stroke:#4285f4
    style LOC fill:#e6f7ed,stroke:#2da44e

The hosted model collects; the local side archives. It reads what it is allowed to see and deposits exactly one kind of thing — a structured report — into an inbox. Everything that changes the shape of the archive happens locally, under review.

The tool surface is the security boundary

No delete, no rename, no move, and nothing that writes to the structured record — history, medication lists and measurement series are unreachable from the remote end.

And the report contract is enforced in code, not requested in the prompt. A report missing any of its six required sections fails the tool call:

missing = [s for s in REPORT_SECTIONS if s not in content]
if missing:
    raise ValueError(...)          # -> "report is missing required sections: ..."

The six sections: Summary, User's own words, Transcribed documents, Advice given, Self-measured values, Hand-over to the local side. The one that carries the most weight is the verbatim one — because the paraphrase is where detail silently disappears.

Every rule in this section is pinned by tests/: the suite starts the real HTTP server over a throwaway archive and attacks it through the same three gates a client passes — wrong path, wrong token, ../ traversal, another member's files, a report with a section missing.

Three independent layers, all of which must pass:

1. A long random path — the endpoint is mounted at /mcp-<path_token>, and the URL alone is unguessable.

2. A bearer token — compared with hmac.compare_digest, resolving to an identity attached to the request.

3. A small, read-biased tool surface — plus scope checks on resolved paths, so ../ cannot escape:

p = (ARCHIVE / rel).resolve()
if not p.is_relative_to(ARCHIVE):
    raise ValueError(...)          # -> "path escapes the archive"

Each bearer token maps to {member, scope}: a self token reaches only its own member directory, all is unrestricted. Adding someone is one line and a restart; revoking is deleting that line.

The host exposes no inbound ports — the tunnel dials out. Path token and bearer token live in separate files so either can be rotated alone.

⚠️ Known limitation. Static bearer tokens are not part of the MCP authorization spec, which expects OAuth. This works because the client accepts a static access token; if that changes, this is the piece to replace.

The whole system rests on one choice: the archive is a directory, not a database. Every layer above it is replaceable, because none of them owns the data.

health-archive/
├── docs/                        shared rules and operating procedures
└── members/<name>/
    ├── allergies-medication.md  safety-critical — read before any advice
    ├── history.md               entries tagged active / resolved / ruled-out
    ├── follow-ups.md            due dates and questions for the next visit
    ├── index.md                 timeline — the index into everything below
    ├── originals/YYYY/          scans, PDFs, photos — never edited, never deleted
    ├── notes/YYYY/              narrative notes derived from those originals
    ├── measurements/*.csv       self-measurement series
    └── inbox/                   📥 the only path this server can write to

Originals are never modified, so everything else can be rebuilt from them; the structured files are a projection, not the source of truth, which makes a bad write recoverable rather than fatal. Files are named by report date, not filing date, so the timeline stays true when a document arrives late.

Directory names and section headings are part of the machine-checked contract, so the code ships them in English; INBOX_DIRNAME renames the write path for a localized archive (the reference deployment runs a Chinese one). Report content follows the language of the conversation.

The prompt file is part of the system on purpose: authority lives in code, behaviour lives in the prompt, and keeping the prompt in the repo is what keeps the two in sync when a tool contract changes.

git clone https://github.com/kevinave/family-health-mcp.git
cd family-health-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env                     # then set ARCHIVE_PATH
cp tokens.example.json tokens.json       # then generate real tokens
python3 -c "import secrets; print(secrets.token_hex(24))" > .path_token

set -a; source .env; set +a
python3 server.py

Generate one token per person with secrets.token_hex(24) and add it to tokens.json as "<token>": {"member": "alice", "scope": "self"}. Each member needs members/<name>/ to exist before save_report will accept anything for them.

Expose the server through a tunnel (it binds 127.0.0.1:8787 by default; HOST and PORT are environment variables) and add the URL as a developer-mode MCP connector: https://<your-host>/mcp-<path_token>, auth = access token, scheme = bearer. deploy/ has example launchd and cloudflared configuration.

Finally, paste prompts/chatgpt-project-instructions.md into the client's project instructions — that is the behavioural half of the system.

The test suite needs none of the above — no archive, no tokens, it builds its own:

pip install -r requirements-dev.txt && pytest

read_file deadlocked while list_dir and search looked fine. The archive lives in a cloud-synced folder; under disk pressure the OS had evicted files to dataless placeholders, and reading one synchronously inside a single-threaded event loop deadlocked. What made it look like one broken tool was search's own except OSError: continue, which swallowed the identical error. The fix belonged in the storage layer, not in the server.

After renaming a tool, the unrenamed ones kept working. Client-side tool lists are cached. Any change to the tool set now ends with: refresh the connector, then start a new conversation.

Scope

A personal system published as a reference implementation, not a product. It assumes one trusted operator and an archive that fits on a single machine.

MIT © kevinave