Umbryn MCP

umbryn-mcp

An MCP server that redacts PII/PHI from text before it ever reaches an LLM — self-hosted, fail-closed, and HIPAA-aware.

Teams building LLM and agent pipelines in regulated domains have no clean, drop-in way to strip PHI/PII from a payload *before* it crosses into a model provider's infrastructure. umbryn-mcp is that boundary: three MCP tools — redact, restore, detect — that scrub sensitive values into reversible placeholders, run entirely inside infrastructure you control, and block the request if detection is uncertain instead of leaking data.

redact("Patient MRN: 1234567, provider NPI 1234567893, ssn 078-05-1120, john.doe@example.com")

redacted_text (safe to send to the model): "Patient MRN: [MEDICAL_RECORD_NUMBER_1], provider NPI [NPI_1], ssn [US_SSN_1], [EMAIL_ADDRESS_1]"

token_map (kept local, never sent to the model): [MEDICAL_RECORD_NUMBER_1] → 1234567 [NPI_1] → 1234567893 [US_SSN_1] → 078-05-1120 [EMAIL_ADDRESS_1] → john.doe@example.com

Send the redacted text to the model; keep the token_map local; call restore afterward to rehydrate the result. Round-trips are byte-exact and proven with property-based tests.

Why this exists

The PHI/PII-redaction MCP niche is real but underserved — the existing options are thin Presidio wrappers with no HIPAA-specific detection and, critically, no guarantee that a detection failure blocks the request instead of silently passing raw data through. So teams either roll their own boundary or ship sensitive data to a provider and lean on a BAA to cover it — the design-time mistake that causes real compliance incidents.

Why it was built: MCP went mainstream fast — it's now first-class in Claude, Cursor, and ChatGPT, across thousands of servers — but the PHI/PII-redaction corner was left to a few unmaintained wrappers. This fills that gap with a single honest, auditable, fail-closed boundary, kept open source so the redaction logic you depend on is fully inspectable rather than a black box.

Features

• Three tools, one boundary — redact (→ scrubbed text + reversible token map), restore (→ original), detect (→ entities found, no mutation).
• Fail-closed by construction — if detection errors *or any detection lands below the confidence threshold*, the call returns a typed error. Uncertainty blocks; it never redacts-what-it-can and passes the rest.
• HIPAA-aware detection — checksum-validated NPI and DEA, position-typed Medicare MBI, context-anchored MRN, CLIA lab IDs, plus standard PII (email, phone, SSN, credit card, IBAN, IP, URL).
• Zero-egress, self-hosted — the default engine is pure regex + checksums with no network calls and no heavy dependencies. It installs anywhere Python does.
• Optional ML upgrade — pip install "umbryn-mcp[presidio]" adds Microsoft Presidio + spaCy for PERSON/LOCATION NER, transparently.
• Reversible & deterministic — collision-proof typed placeholders make restore(redact(x)) == x for *arbitrary* input; same input + config always yields the same output.

When to use it (and when not to)

Reach for `umbryn-mcp` when:

• You send healthcare, clinical, financial, or user-generated text to a third-party LLM API and need PHI/PII kept out of that provider's infrastructure and logs.
• You're building an agent or MCP pipeline in a regulated domain and want a drop-in scrubbing boundary you wire in with one tool call.
• You need reversible redaction so downstream steps still work: redact → send to model → restore.
• You want a self-hosted, no-egress detector you can audit line by line.
• You need HIPAA-specific identifiers (NPI, DEA, Medicare MBI, MRN, CLIA), not just names and emails.

Reach for something else when:

• You need irreversible de-identification / anonymization (tokenization, k-anonymity) — redaction here is reversible by design.
• You need to redact non-text data (images, audio, PDFs, database rows) — scope is text.
• You want a certified compliance product — this is one technical control, not a compliance program (see Scope & honest limitations).
• You want a transparent proxy that auto-scrubs everything in the request path — v1 is explicit tool calls; proxy mode is on the roadmap.
• You require guaranteed 100% recall — no detector, this one included, can promise that.

Quickstart (< 60 seconds)

pip install umbryn-mcp        # zero heavy deps; runs immediately

Then register it with your MCP client.

Claude Desktop / Claude Code (claude_desktop_config.json, or claude mcp add umbryn-mcp -- umbryn-mcp):

{

"mcpServers": { "umbryn-mcp": { "command": "umbryn-mcp" } } }

Cursor (.cursor/mcp.json) and VS Code use the same shape — see examples/ for ready-to-paste configs.

Want name/address detection too?

pip install "umbryn-mcp[presidio]"

python -m spacy download en_core_web_lg

The server auto-detects Presidio and upgrades — no config change needed. (Set UMBRYN_ENGINE=regex to force the dependency-free engine, or =presidio to require the ML one.)

How it works

A tool call comes in over stdio; the Redactor core runs the configured detection engine, resolves overlaps deterministically, applies the fail-closed threshold check, and swaps detected spans for reversible typed placeholders. Only scrubbed text is meant to leave the boundary you run.

flowchart LR

A[MCP client Claude · Cursor · agent] -- redact / restore / detect --> B[umbryn-mcp stdio server] B --> C[Redactor core fail-closed · reversible] C --> D{Detection engine} D -->|default, zero deps| E[Regex + checksums] D -->|optional| F[Presidio + spaCy NER] C -. scrubbed text .-> A A -- scrubbed text only --> G[(LLM / downstream)]

The Redactor core depends only on a small DetectionEngine interface — never on Presidio or MCP directly. Raw data and the detection engine stay inside the boundary you run; only scrubbed text leaves it. See docs/ARCHITECTURE.md and docs/THREAT_MODEL.md.

The tools

redact(text) → { redacted_text, token_map, entities }

Replaces detected PHI/PII with typed placeholders like [NPI_1]. token_map maps each placeholder back to its original value — keep it local; never send it to the model. entities lists what was redacted (type/span/score) for auditing.

restore(redacted_text, token_map) → { text }

Reverses a redaction, recovering the original text exactly. Safe to call on model output that still contains the placeholders.

detect(text) → { entities, count }

Reports the entities found — type, span, confidence — without modifying the text. Unlike redact, it surfaces low-confidence hits rather than blocking, so you can inspect coverage before trusting the boundary in a pipeline.

How to use it (a real pipeline)

The pattern is redact → model → restore, with the token map never leaving your side:

1. Scrub before the model. Call redact(user_text). Send only redacted_text to the LLM. Keep token_map in your process — treat it as sensitively as the raw input, and never pass it to the model.
2. Let the model work on placeholders. It sees [NPI_1], [US_SSN_1], etc. — semantically neutral tokens it can reason about and echo back.
3. Rehydrate after. Call restore(model_output, token_map) to swap the real values back into the model's response before it reaches your user or database.
4. Handle the block. If redact returns a [LOW_CONFIDENCE] or [DETECTION_ERROR] tool error, the boundary refused to leak — surface it, tighten input, or lower the risk, but don't send the raw text onward.

Before trusting it in a pipeline, call detect(sample_text) on representative (synthetic) data to see exactly what is and isn't caught, and tune the thresholds (below) to your risk tolerance.

Fail-closed, precisely

Two thresholds govern every redact call:

• `detection_floor` (default 0.35) — the sensitivity boundary. Signals below it are treated as noise.
• `min_confidence` (default 0.5) — the *trust* threshold.

Any candidate that survives the floor but scores below `min_confidence` puts the call into fail-closed mode: it returns a [LOW_CONFIDENCE] error rather than redacting the confident spans and passing the uncertain one through. Engine errors return [DETECTION_ERROR]. On any error, no redacted text is returned. Both thresholds are configurable (see below).

Configuration

All optional; sane defaults mean it runs with zero config. Set via the client's env block.

Config file

For settings that don't fit a flat environment variable, point UMBRYN_CONFIG at a JSON file. Environment variables still win over the file for the scalar values above, so you can ship one file and tweak per launch. A malformed file (bad JSON, unknown threshold, un-compilable regex) fails closed at startup rather than degrading silently.

{

// Per-entity trust thresholds override min_confidence for that type. "entity_thresholds": { "PHONE_NUMBER": 0.7, "IP_ADDRESS": 0.9 },

// Entity types to drop entirely — never detected, never redacted. // (A privacy trade-off you're opting into: a disabled type can leak.) "disabled_entities": ["URL"],

// Your own recognizers, no fork required. validator names a built-in // check-digit function (luhn, npi, dea, iban, nhs) — config supplies data, // never code. "recognizers": [ { "entity_type": "EMPLOYEE_ID", "regex": "\\bEMP-\\d{6}\\b", "base_score": 0.85, "context": ["employee", "badge"], "context_required": false } ],

"audit_log": true }

A ready-to-copy example lives at [`exampl