SafeHarbor MCP

A guarded Model Context Protocol server that lets AI agents analyze healthcare claims without ever touching PHI.

Every health plan wants analysts to ask Claude "what's our lumbar MRI denial rate by plan?" Almost none can hand an agent a connection to a claims warehouse full of names, SSNs and clinical notes. SafeHarbor is the layer in between: a zero-dependency MCP server that exposes a de-identified mart and enforces privacy inside the database engine, not with SQL regexes an agent can talk its way around.

 Claude / any MCP client
          │  JSON-RPC over stdio
          ▼
 ┌──────────────────────────── SafeHarbor ────────────────────────────┐
 │ query(sql, purpose) ──► read-only conn ──► authorizer ──► engine   │
 │                         query_only         tables,        k-supp.  │
 │                                            functions,     aggregates│
 │                                            statements     VM budget │
 │                         hash-chained audit log ◄── every call       │
 └─────────────────────────────────┬──────────────────────────────────┘
                                   ▼
                     de-identified mart (mart.db)
                                   ▲  build_mart(): pseudonymize, generalize, drop free text
                     raw warehouse (PHI) — never opened by the server

Results

From reports/REDTEAM.md, generated by python -m safeharbor.redteam:

Related MCP server: Claims Data MCP Server

How it works

1. Physical separation, not just views. build_mart() materializes de-identification views (pseudonymous member_token, 10-year age bands, 3-digit ZIP, service month, no names/SSN/DOB/address/contact/notes) into a separate file. The server only ever opens that file.

Why not guard views over the raw tables? That was the first design. The red-team found the bypass: SQLite resolves a CTE before a view of the same name, so WITH v_members AS (SELECT first_name, last_name, ssn FROM members) SELECT * FROM v_members runs with the authorizer believing every read came from the approved view. View-level column policies can't distinguish the two. Case A32 keeps that attack in the suite as a regression test.

2. Engine-level authorization. SQLite's authorizer callback is consulted for every table read, column read, function call and statement type while the query is compiled. SafeHarbor allows reads of the three mart tables only (CTE references are recognized by their null database name; virtual tables like pragma_table_info and dbstat are not), an allow-list of functions, and SELECT. Everything else (PRAGMA, ATTACH, writes, DDL, transactions, load_extension, group_concat, window functions) is denied before a single row is read. The connection is also opened mode=ro with PRAGMA query_only.

3. Small-cell suppression inside the engine. count, sum, total, avg, min and max are replaced with implementations that return NULL when computed over fewer than k = 11 rows (the CMS cell-size threshold). Because it happens at the source, derived values are covered too: count(*) + 0, sum(1), HAVING count(*) < 11 probes and single-member averages all come back empty.

4. Resource limits. A VM-instruction budget and wall-clock deadline (via the progress handler) kill runaway recursion and cartesian joins; results are capped at 500 rows.

5. Purpose + tamper-evident audit. The query tool requires a stated purpose (HIPAA minimum-necessary). Every call (client name, purpose, SQL, normalized fingerprint, decision, reason, rows, suppressed cells, latency) is appended to a SHA-256 hash-chained JSONL log. Editing, deleting or reordering any line is detected by python -m safeharbor.audit logs/audit.jsonl.

6. Prompt-injection hygiene. One synthetic provider's practice_name contains an injected instruction to dump SSNs. Responses mark free-text columns as untrusted_columns, and the injected query is blocked regardless (A33): defense doesn't depend on the model behaving.

Agent-friendly errors. Denials explain themselves ("read of sqlite_master.type is not permitted; available tables: [...]", "query exceeded the compute budget; add filters or aggregate") so an agent can correct course instead of retrying blindly.

Quick start

pip install -e ".[dev]"
python -m safeharbor.data          # builds data/raw_warehouse.db and data/mart.db (synthetic, seeded)
python -m safeharbor.redteam       # runs the suite, writes reports/REDTEAM.md
pytest -q

Use it from Claude Desktop or Claude Code

{
  "mcpServers": {
    "safeharbor": {
      "command": "python",
      "args": ["-m", "safeharbor.server", "--mart", "data/mart.db",
               "--policy", "policy.toml", "--audit", "logs/audit.jsonl"],
      "cwd": "/absolute/path/to/safeharbor-mcp"
    }
  }
}

Claude Code: claude mcp add safeharbor -- python -m safeharbor.server --mart data/mart.db from the repo directory.

Then ask: "What's the denial rate by provider specialty, and how does out-of-network allowed cost compare to in-network?"

Policy

All rules live in policy.toml: allowed tables, allowed functions, k, row cap, compute budget, untrusted text columns. Anything not listed is denied.

Known gaps

Documented in the report and kept in the suite:

• Differencing (G01). Two large, allowed counts that differ by one person can be subtracted. Per-query suppression can't stop this; it needs cross-query auditing or differential privacy.

• Quasi-identifiers (G02). Row-level pseudonymous records are allowed for drill-down. A rare ZIP3 + sex + age-band combination can still single someone out.

• Utility cost of fail-closed suppression (G03). Per-member aggregates inside a CTE are nulled before the outer query sees them. The mitigation is the FDE one: precompute common member-level features into the mart (members.claim_count).

Layout

safeharbor/
  data.py      synthetic raw warehouse (PHI) + de-identification views + build_mart()
  guard.py     authorizer, k-suppressed aggregates, budgets, row cap
  server.py    MCP stdio server (JSON-RPC 2.0, protocol 2025-06-18 / 2025-03-26 / 2024-11-05)
  audit.py     hash-chained audit log + verifier
  redteam.py   attack / utility / gap suites + PHI canary scan
policy.toml    the access policy

All data is synthetic and generated from a fixed seed. Python 3.11+, no runtime dependencies.

License

MIT