Docs / Guide: Protect personal data

Protect personal data end to end

This guide is for the person who sets up data protection for a team. It covers the gateway, name detection, maisecrets on every laptop, Sensitive References, updates and the final check. Give it to that person as it is.

Two layers, one picture

Personal data reaches an AI model on two paths. Each path has its own guard.

Where the data comes fromWho protects itWhat the model gets
A company tool: Jira, CRM, mail, ticketsmcpgate (the gateway)A token such as ⟦EMAIL_1⟧
The laptop: a prompt, a file, a commandmaisecrets (free plugin)A placeholder such as ⟦SECRET_c1⟧

Each layer works alone. Together they cover both paths. The detail and a diagram: maisecrets with mcpgate.

What you set up, in order

  1. The gateway level: on by default; choose how much a token shows.
  2. Name detection: optional; a container that finds persons in running text.
  3. maisecrets for everyone: a private marketplace and a machine policy.
  4. Updates: decide who takes a new version.
  5. Sensitive References: optional; real values into local files.
  6. The check: prove each layer once.

1. The gateway level

From v2.0.3960, a new installation masks personal data from the first call. You do not need to switch it on. The gateway replaces e-mail addresses, phone numbers, IBANs, card numbers, IP addresses, account and ID numbers, tax IDs and birthdays in tool results. Secrets such as tokens and passwords are removed and never put back.

When the AI writes to a tool, the gateway puts the real value back into the call. The mapping between token and value stays in Redis, encrypted (AES-256-GCM), until 24 hours after its last use.

Choose the level

Open Protection > Data Sanitization (/admin/pii). Set Default level for all services, and add an exception only for a service that needs another level. The level changes only what the token shows. The write-back works on every level.

LevelWhat the token shows
Redacted (default)Only the key: ⟦EMAIL_1⟧
MaskedThe first 2 characters; the domain only for a freemail address
Masked LiteThe first 2 characters and the full domain
CleartextThe real value. Only for a service without personal data.

Redacted is the only level whose token carries nothing of the value. The visible part of the other levels is still personal data.

To switch the protection off on purpose, set FEATURE_PII_SANITIZATION=false in the gateway environment. An unset variable keeps it on.

2. Name detection (optional)

A name has no fixed shape. The rules find a name only after a label, such as "Name:". A name service finds persons in running text. It runs as a second container, mcpgate/ner, and is part of the Enterprise plan.

Pick the host

SetupCPURAM
On the gateway host4 vCPU with VNNI or dotprod8 GB
On its own host2 to 4 vCPU with VNNI or dotprod2 to 4 GB

VNNI (x86) or dotprod (ARM) makes the service 2.2 to 2.4 times as fast. To check a server: grep -oE 'avx512_vnni|avx_vnni|asimddp' /proc/cpuinfo | sort -u. Empty output means the slower fp32 model. Which servers have it.

Start it on the gateway host

cd ~/.mcpgate
docker compose --profile ner up -d
echo 'NER_SERVICE_URL=http://172.31.250.2:8765/' >> .env
docker compose up -d

The container gets a fixed address in a private network of the compose project, with 3 CPUs and 1.5 GB at most.

Or start it on its own host

docker run -d --restart unless-stopped --cpus 4 \
  -e NER_CLIENT_SECRET=<secret> \
  -p <private-ip>:8765:8765 mcpgate/ner:latest

On the gateway host, add NER_SERVICE_URL=http://<private-ip>:8765/ and the same NER_CLIENT_SECRET to ~/.mcpgate/.env, then run docker compose up -d. The URL must be an IP address, not a host name.

Turn it on

  1. On /admin/pii, card Detector, choose Baseline + name detection. The page refuses this choice while no service answers.
  2. In the card Name detection for clients, turn on Cache name detection results. It cuts the load of the container to about a quarter. It keeps positions, labels and scores in memory, never text.
  3. For maisecrets users who should use this service (step 3), set Name detection for clients to Allow.

If the service does not answer, the gateway holds the tool result back. It does not send it unchecked. No setting changes that.

The gateway's container does not update itself. To take a new image: docker compose --profile ner pull && docker compose --profile ner up -d (or docker pull and a new docker run on its own host).

3. maisecrets for everyone

maisecrets runs inside Claude Code, Cowork and Codex on each laptop. It needs Python 3.9 or newer. An admin can make it required, so that the protection does not depend on each person.

Distribute it

  1. Create a private marketplace repository on GitHub or GitLab. The organisation sync accepts a private or internal repository only. Put a .claude-plugin/marketplace.json in it that lists maisecrets with https://github.com/Mcpgate-de/maisecrets as its source. Or mirror the repository (see updates).
  2. Claude (Claude Code, Cowork): in the claude.ai organisation settings, under Plugins & Skills > Marketplaces, add the repository. GitHub works through the Claude GitHub App. For GitLab, first add a GitLab configuration under Git providers. Turn on automatic sync: it creates a webhook in the repository, so you need admin rights on it. Then set maisecrets to required or installed by default.
  3. ChatGPT workspace (Codex): Admin > Plugins > Import marketplace, with the same file. The import delivers maisecrets with its hooks (seen with 0.9.13 in November 2026; an import in October 2026 came without them). Each person trusts the hooks once in Settings > Hooks, and again after each update. A workspace admin can ship them as managed hooks through requirements.toml and your MDM; then policy trusts them.

More detail: maisecrets for your company.

Set the machine policy

A machine policy wins over each person's settings. Put one JSON file on every laptop, for example with your MDM:

SystemPath
macOS/Library/Application Support/maisecrets/policy.json
Windows%ProgramData%\maisecrets\policy.json
Linux/etc/maisecrets/policy.json

The keys that matter for this guide:

KeyWhat it doesDefault
remote_detectorThe name service, for example the one of your gateway (see below). The policy object replaces the person's whole setting, so /maisecrets:ner cannot change anything in it.off
rule_dirsFolders with your team's rules and *.terms files with customer or case names. Users keep their own folders and cannot remove yours.none
show_valuesalways, click or off: whether a masked value shows on the person's own screen. A password never shows.always
rehydrationautomatic, confirm or block. confirm asks before maisecrets puts a real value into a command, a file or an MCP call (Codex refuses instead); block never puts one in. Any other value counts as block.automatic
read_pdfallow, ask, convert or block. With convert, maisecrets turns a PDF into text and masks it.allow
regionsCountries whose ID numbers count as personal data.the country of the system
report_urlnull turns bug reports off.GitHub issues

A person cannot change a key that the policy sets. /maisecrets:status names the keys that come from the policy.

Use the gateway's name service on every laptop

With this, a laptop needs no container of its own. Each tool result goes to the gateway over https, with the person's sign-in. Each value that the rules found goes as a filler, so the service never gets it. The setting is the same for everyone; the sign-in is personal.

  1. On one laptop, run /maisecrets:ner gateway <MCP URL of your gateway>. Use the same MCP URL that your users have, not only the host.
  2. Copy the remote_detector object from ~/.maisecrets/config.json of that laptop into the policy. It holds no personal data. If typed prompts should go to the service too, add "prompts": true to the object; under a policy, a person cannot turn it on.
  3. Make sure that each person has the gateway as an MCP server in their own user configuration.
  4. Each person runs /maisecrets:sref login once after the policy arrives, also a person who logged in before. Until then, the name service checks nothing on that laptop.
  5. Check each laptop with /maisecrets:ner.

Without an answer from the service, the rules mask the result alone, and the screen says "names not checked".

Only prompts that a person types in Claude Code go to the service, never from claude -p or the Agent SDK. In Codex, prompts keep the rules alone.

4. Updates

Decide who takes a new version, and name that person.

Source of your marketplaceWhat happens
The public repositoryEach release reaches everyone at the next session start. In Codex, a release can come later, and it works only after the hooks are trusted again.
A mirror that you controlA release reaches everyone only after you take it into the mirror. To go back, publish the previous code with a new, higher version number.
  • Open sessions: after an update from the organisation sync, an open session can lose its hooks. A guard then blocks that session. To fix it, exit and run claude --resume <session id>; the guard puts this command on the clipboard. /reload-plugins is not enough. In Codex, exit and run codex resume.
  • Codex: each person trusts the hooks again after each update, unless you ship managed hooks.
  • Local name service: each plugin version pins one image of mcpgate/ner. A laptop with a local container takes the new image at the next session start. The new image downloads while the old container runs. For a few seconds of the change, the rules work alone. If the new container fails, the old one comes back. /maisecrets:ner updates off keeps the image. A container started by hand is never replaced.
  • The gateway and its name service: you update them yourself (see step 2).

5. Sensitive References (optional)

Sometimes a real value must go into a local file, for example a customer's address into a letter. The model only knows the token. With Sensitive References, maisecrets asks the gateway for the value at the moment it writes the file. The model never sees the value. This is part of the Team plan.

  1. The gateway must be an MCP server in each person's own user configuration.
  2. Each person runs /maisecrets:sref login once (in Codex: run.sh sref login in a terminal). The browser opens; the person signs in to the gateway and agrees.
  3. The gateway admits every member and guest, minus a block list. A person resolves only references that the gateway issued to that person.
  4. To stop one person: on /admin/pii, card Local vaults, enter the e-mail address, then Block or Revoke.

Remember: the file then holds the real value in plain text. If the AI reads that file later, it sees the value. Tested in Claude Code. More: Sensitive References.

6. The check

Do this once after the rollout, and again after a large update.

  1. Gateway: on /admin/pii, paste a text with an e-mail address and a name into Try a text. Then ask the AI to read a ticket that holds an e-mail address: the answer shows a token.
  2. Counts: Evidence > Sanitization Stats (/admin/sanitization-stats) shows how many values the gateway replaced, per class and service.
  3. maisecrets loads: each new session starts with the line maisecrets X.Y.Z is on. (with team rules: "…is on, with N rules of your own from M folders"). No line means the plugin did not load.
  4. maisecrets works: /maisecrets:status shows a verdict per check. /maisecrets:status test proves both paths: type the test value it prints, and maisecrets answers "Self-test passed" without sending it.
  5. Name service: /maisecrets:ner shows the source, whether it answers and which image runs.
  6. Sensitive References: /maisecrets:sref shows the server and whether the person is signed in.

What the layers do not catch

The gateway

  • Text inside PDFs, images and attachments, and values in Base64 or other encodings.
  • A tool result above the inline limit: it goes to the client as a download, unmasked.
  • Without name detection: a name without a label. With it: persons only; companies and places stay text.

maisecrets

  • Text in images and scanned PDFs; text in a PDF unless the policy sets read_pdf to convert.
  • A value that a command changes with an encoding before it prints it. maisecrets itself decodes Base64 and hex.
  • The output of a failed command in Claude Code.
  • Without name detection: a name that has no label and is not on a term list. With it, by default: persons only.
  • A client without hooks: the ChatGPT and Claude chat apps, web and mobile, and Codex until a person trusts the hooks.
  • A person with administrator rights on the laptop can change the policy or remove the plugin.

The full lists: maisecrets limits and name detection in the gateway.