Claude Code
Add the Redact PDF AI server to a repository so that everyone who works in it with Claude Code can redact a document before it is committed, attached to an issue or sent to a vendor.
Runnable files: https://github.com/dambuchs/redact-pdf-mcp/tree/main/examples/claude-code.
Add the MCP server
For yourself:
claude mcp add redact-pdf --env REDACT_PDF_API_KEY=YOUR_KEY -- npx -y redact-pdf-mcp@0.6.0
Put the server name before --env: --env takes every KEY=value that follows it, so a name written after it is read as one more variable.
For the whole team, commit a .mcp.json at the repository root. ${REDACT_PDF_API_KEY:-} is read from each person's environment, so no key is committed (the :- keeps the file valid for someone who has not set it):
{
"mcpServers": {
"redact-pdf": {
"command": "npx",
"args": ["-y", "redact-pdf-mcp@0.6.0"],
"env": { "REDACT_PDF_API_KEY": "${REDACT_PDF_API_KEY:-}" }
}
}
}
The hosted connector works too, with OAuth sign-in and no key: claude mcp add --transport http redact-pdf https://mcp.redact-pdf.ai/mcp. See the Claude connector reference.
Add a skill
A skill tells Claude when and how to use the tools. Save this as .claude/skills/redact-outgoing/SKILL.md in the repository. The allowed-tools line approves the two tools while the skill runs; it does not block other tools.
---
name: redact-outgoing
description: Redact personal data from PDFs, scans or screenshots in this repository before they are committed, attached to an issue, shared with a vendor or sent outside the company. Use when asked to redact, anonymize or clean a document before it leaves, or when a file under outgoing/ needs to be prepared.
allowed-tools: mcp__redact-pdf__redact_pdf_and_wait mcp__redact-pdf__restore_names
---
# Redact documents before they leave
Uses the `redact-pdf` MCP server from `.mcp.json`. Keep this file at `.claude/skills/redact-outgoing/SKILL.md` in the repository, next to `.claude/settings.json`: this skill only guides Claude, the deny rules in that file are what stop it reading the tables, the restored files and the originals under `outgoing/`.
## Never open the original
Do not Read, cat or preview the document before it is redacted. Pass its path to the tool and nothing else. The same goes for any `-correspondence.csv` and `-restored` file: they hold the real names.
## Keep the outputs out of git
The `-correspondence.csv` and `-restored` files hold the real names, and the originals are what you are protecting. They are written next to the original. Check that `.gitignore` covers them (for example `*-correspondence.csv`, `*-restored.*` and the folder that holds originals) before running `git add`.
## Redact (black boxes)
1. Call `redact_pdf_and_wait` with `file_path` set to the absolute path and `pii_categories` set to `["Person", "Email", "PhoneNumber", "Address", "Organization", "Date", "IBAN", "CreditCard"]`, unless the user asked to keep some of them.
2. Report `output_path` (the `-redacted.pdf` next to the original). If the result lists `categories_not_redacted`, tell the user those stay in the file.
3. Only the `-redacted.pdf` may be committed or sent. Remind the user that the original is unchanged.
## Work on it without seeing names
1. Call `redact_pdf_and_wait` with `mode: "pseudonymize"` and the same `pii_categories` list. If the result lists `categories_not_redacted`, stop and ask the user: names or other details would be in the text you read.
2. Work from `document_text` (or the file at `document_text_path`), keeping tags such as `[Person 1]` exactly as written.
3. Write the result to a `.md` file, then call `restore_names` with that file and `correspondence_path`. Do not pass `output_path`: the default `-restored` name is the one the deny rules cover.
4. Give the user the restored file's path. Do not open it. If `replacements` is 0, say that no tag was found and nothing was restored.
Deny reads of the names
The skill only asks Claude not to open the table, the restored files and the originals. Claude Code reads any file in the project without asking by default, and text inside a document can ask it to. Commit these deny rules as .claude/settings.json; they hold whatever the model is told:
{
"permissions": {
"deny": [
"Read(**/*-correspondence.csv)",
"Read(**/*-restored.*)",
"Read(./outgoing/**/*.pdf)",
"Read(./outgoing/**/*.png)",
"Read(./outgoing/**/*.jpg)",
"Read(./outgoing/**/*.jpeg)"
]
}
}
Adjust outgoing/ to the folder that holds your originals. The rules cover Claude Code's file tools (Read, and the search tools that read files), not shell commands: do not auto-approve Bash in this repository.
The two patterns
- Redact before a document leaves the company: "Redact outgoing/lease-2026.pdf before I attach it to the ticket." Claude calls
redact_pdf_and_waitand gives yououtgoing/lease-2026-redacted.pdf. - Pseudonymize → work → restore names: "Summarize the obligations in outgoing/lease-2026.pdf without reading the names." Claude pseudonymizes, writes the summary from the tagged text, and calls
restore_names, which writes a-restoredcopy of that summary with the real names, next to it. Claude gets only the path and counts;replacements: 0means no tag was found.
The outputs are written next to the original, inside the repository. Add *-correspondence.csv, *-restored.* and the folder that holds originals to .gitignore before anyone runs git add .: the table re-identifies every redacted file.
The Claude plugin ships two ready-made skills for these patterns (redact-before-sharing and anonymize-before-ai): /plugin marketplace add dambuchs/redact-pdf-mcp, then /plugin install redact-pdf-ai@redact-pdf-ai. See the Local MCP server page.
Keep the names away from the model
- Pass the document by path. Never let the agent Read, cat or preview the original, the
-correspondence.csvor the-restoredfile: those hold the real names. - Ask for
pii_categories(all eight), as the skill does; in Claude Code it is the model that makes the call, so checkcategories_not_redactedin what it reports. Withoutpii_categories, the account's saved dashboard categories decide, and one unticked there (Person, say) stays in the output. The result then lists it incategories_not_redacted. - The account's saved "never redact" terms (Dashboard → Settings) still apply to MCP jobs: the MCP tools cannot send an empty list to override them. If you have whitelisted names there, they stay in the text the model reads.
- Text inside a document can try to steer an agent. In Claude Code the skill is guidance only: the
.claude/settings.jsondeny rules are what stop Claude reading the tables, the restored files and the originals. They cover Claude Code's file tools, not shell commands, so do not auto-approveBashin this repository. - In pseudonymize mode the model sees everything that is not a detected entity, health or financial details included, and any name the detection missed. If that is too much, use redact mode.
- File names reach the model when the agent passes paths: give confidential files neutral names.
- Traces and transcripts keep what the model saw, the tagged text included: OpenAI Agents SDK tracing (on by default; the example turns it off), LangSmith when
LANGSMITH_TRACINGis set, and the session transcripts Claude Code and the Claude Agent SDK write under~/.claude/projects. - Jobs default to
retention: "ephemeral": the original is deleted right after a successful redaction, and the outputs when your account's retention window ends. See Retention.
Related pages
- Local MCP server: every tool and option
- Pseudonymize mode
- Retention
- AI assistants overview