Skip to main content

obscate-mcp

An MCP server that gives any AI agent reversible PII redaction. Your agent redacts personal data before a payload leaves (for another model, a tool or a third-party API), then restores the real values in the reply.

It is a thin wrapper over the Obscate HTTP API. Full docs: obscate.com/docs/mcp. Detection runs in the API (hosted, or your own self-hosted instance). This package only forwards calls.

tool what it does API units
redact redact a text; default fpe keeps formats and needs no map to restore 1 per 100 KB
restore put the original values back free
detect classify what PII a text contains (labels, offsets, counts) without changing it 1 per 100 KB
redact_json redact values inside a JSON object/array; keys and shape are unchanged 1 per 100 KB
restore_json restore any JSON reply free
list_entities supported labels and strategies free, no key

What to expect from detection: structured IDs (email, phone, cards, Aadhaar, PAN, GSTIN, IBAN, SSN, IPs, AWS keys) are near-perfect because they are regex- and checksum-based. Names and places come from an NER model and are best-effort. Check the output if recall on those matters to you. (Detectors and accuracy, benchmark methodology.)

Known limitation: partial values come back wrong

If the model quotes only part of a redacted value ("your card ending in 7588", "the email starting with…"), restore can't fix it: it matches whole tokens, and a fragment isn't one. With fpe this fails silently and plausibly. The fake card looks like a real card, so its last four digits look like real digits, and your user sees a confident, wrong statement about their own data. Assistants paraphrase values like this all the time, so expect it in normal use.

What we measured with real Claude (claude-haiku-5-5, a support-reply prompt, 3 runs each; a small test, not a guarantee):

setup replies stating wrong card digits
fpe, plain prompt 2 of 3
fpe + the instruction below in the system prompt 0 of 3
tokenize, plain prompt 0 of 3

For user-facing output where the model may paraphrase values:

  • Add to your system prompt: "When you mention a card number, email or phone number, repeat it exactly and in full as given. Never abbreviate, mask or quote part of it."
  • Or use strategy="tokenize": models treat [CREDIT_CARD_1] as a unit and don't split it, and restore only touches tokens in its map.

Partial references are a boundary of any reversible-redaction approach, not only ours: once the model only sees a stand-in, a fragment of the stand-in can never map back to a fragment of the original.

Quickstart (about 3 minutes)

  1. Get a free API key at obscate.com (quickstart). It is free for 1,000 requests a month at 60 a minute, with no card. The key is shown once.
  2. Install with one of these:
    uvx obscate-mcp --version          # no install, runs from PyPI
    pip install obscate-mcp            # or install into an environment
    
  3. Add it to your MCP client (below), with the key in the env block.
  4. Ask your agent: "Redact this before you send it to the CRM: Ravi Kumar, ravi@example.com, +91 98765 43210".

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "obscate": {
      "command": "uvx",
      "args": ["obscate-mcp"],
      "env": { "OBSCATE_API_KEY": "ob_..." }
    }
  }
}

Claude Code

claude mcp add obscate --env OBSCATE_API_KEY=ob_... -- uvx obscate-mcp

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (per project). Use the same JSON block as Claude Desktop.

Configuration

env var default
OBSCATE_API_KEY none required for every tool except list_entities
OBSCATE_BASE_URL https://api.obscate.com point at a self-hosted Obscate (the self-hosted edition is in pilot; ask contact@obscate.com)

Do not commit config files that contain the key. If your client supports env files or secret references, use them.

obscate-mcp --transport streamable-http serves over HTTP instead of stdio.

Example agent flow

The agent has a customer record and must create a ticket in a third-party helpdesk tool, which should never see the raw PII.

user:   File a ticket: Ravi Kumar (ravi@example.com, +91 98765 43210) was double-charged on card 4242 4242 4242 4242.

agent → redact_json({"json": {"customer": "Ravi Kumar", "email": "ravi@example.com",
                              "phone": "+91 98765 43210", "issue": "double-charged on card 4242 4242 4242 4242"}})
      ← {"redacted": {"customer": "[PERSON:…]", "email": "<email-shaped value>", "phone": "<phone-shaped value>",
                      "issue": "double-charged on card <valid-looking card number>"},
         "type_changes": [], "keys_redacted": false, …}

agent → helpdesk.create_ticket(<the redacted object>)        # the tool only sees redacted values
      ← {"ticket": 812, "summary": "Refund for [PERSON:…], reply to <email-shaped value>"}

agent → restore_json({"json": <the tool's reply>, "type_changes": []})
      ← {"json": {"ticket": 812, "summary": "Refund for Ravi Kumar, reply to ravi@example.com"}}

With strategy: "tokenize" the redacted values look like [EMAIL_1], and you pass the returned token_map to restore / restore_json. With fpe (the default) no map exists. Restore needs only your key, plus the key_version that redact returned. Pass it back to restore or restore_json. It names the version of your account's key that made the tokens, so restore keeps working if Obscate rotates keys in between. If it is left out, the current version is used.

If you store redacted text to restore later, store key_version with it.

fpe caveat: an email, phone number or ID that a model invents, which was never redacted, is indistinguishable from an fpe token. restore will decrypt it into a different value. Restore only text whose structured values came from your own redaction. If that matters, use tokenize, which only replaces tokens that appear in the map. See strategies.

Privacy

  • The server never logs, prints or stores the text, the detected values or the token map. Errors carry the HTTP status and the API's fixed message only. This is enforced by tests/test_server.py::test_privacy_*.
  • redact and detect do not echo the original values back into the model's context (detect can with include_values: true).
  • The Obscate API has the same contract on its side: it does not log or store payloads. The hosted API runs in DigitalOcean Bangalore. Traffic passes through DigitalOcean's Cloudflare edge. See security & limits.

Develop

pip install -e '.[test]' && pytest -q      # unit tests against an in-process fake API
OBSCATE_API_KEY=ob_... python ../scripts/live_e2e.py mcp   # real end-to-end against the live API

License: MIT.

Metadata

Release files for obscate-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for obscate-mcp 0.1.0
File Size Uploaded Provenance Actions
obscate_mcp-0.1.0.tar.gz 15.8 kB Without provenance Details for obscate_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for obscate-mcp 0.1.0
File Interpreter ABI Platform Actions
obscate_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for obscate_mcp-0.1.0-py3-none-any.whl

Total release size: 29.8 kB

Release files / obscate_mcp-0.1.0.tar.gz

Download URL obscate_mcp-0.1.0.tar.gz
Size 15.8 kB
Tags Source
SHA-256 checksum
How to use checksums
3bc425043153ae688f32181cd5a257519d3336e746b8285f04e7147d2949b183
BLAKE2b-256 checksum
How to use checksums
e7013c02617a8db3cda13c6437c482333e87c9f0decf2eaea44eef04700da2e2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Release files / obscate_mcp-0.1.0-py3-none-any.whl

Download URL obscate_mcp-0.1.0-py3-none-any.whl
Size 13.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
75230637a5fa4489e112129ec13800445e2d19bd2178a7852056f48973156b5a
BLAKE2b-256 checksum
How to use checksums
b0493cde472d0428706ed4b904a0485bc0e377879da421576d2aa47ba77c2f58
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.15

Security for obscate-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page