Developer docs

Local MCP server

Install the redact-pdf-mcp server or the Claude plugin in Claude Code, Cowork, Claude Desktop, Cursor, VS Code or Codex. API key setup, tools, local name restore.

Local MCP server and Claude plugin

redact-pdf-mcp is an MCP server that runs on your own computer. It reads documents from your disk by path, sends them to the Redact PDF AI API, and writes the redacted output next to the original. In pseudonymize mode it also puts the real names back on your machine, so the AI assistant never sees them.

Prefer nothing to install? Use the Claude connector instead.

Install

Claude Code: the plugin

The plugin bundles the server with two skills: redact a document before it is shared, and anonymize a document before Claude works on it.

In Claude Code, type:

/plugin marketplace add dambuchs/redact-pdf-mcp
/plugin install redact-pdf-ai@redact-pdf-ai

Cowork

Download the plugin zip, then in Cowork open Customize → Plugins → Add → Upload plugin and choose it. It works in Cowork sessions that run on your computer.

Claude Code: the server only

claude mcp add redact-pdf --env REDACT_PDF_API_KEY=your_key -- npx -y redact-pdf-mcp

Claude Desktop, Cursor and other JSON configs

In claude_desktop_config.json, .cursor/mcp.json or your client's equivalent:

{
  "mcpServers": {
    "redact-pdf": {
      "command": "npx",
      "args": ["-y", "redact-pdf-mcp"],
      "env": { "REDACT_PDF_API_KEY": "your_key" }
    }
  }
}

VS Code

code --add-mcp '{"name":"redact-pdf","command":"npx","args":["-y","redact-pdf-mcp"],"env":{"REDACT_PDF_API_KEY":"your_key"}}'

Codex

In ~/.codex/config.toml:

[mcp_servers.redact-pdf]
command = "npx"
args = ["-y", "redact-pdf-mcp"]
env = { REDACT_PDF_API_KEY = "your_key" }

API key

Create a key in your dashboard. A free account gets its first document (up to 5 pages) redacted in full, with no card. Without a key, try_demo still works.

The server finds the key in this order:

  1. REDACT_PDF_API_KEY in the environment. An empty value, or an unsubstituted placeholder such as ${user_config.api_key}, counts as unset.
  2. A key given to set_api_key in this session that you could not confirm (kept in memory only).
  3. The key file ~/.config/redact-pdf-mcp/key (or $XDG_CONFIG_HOME/redact-pdf-mcp/key).

Clients that can't pass the key in the environment (the Claude plugin in Cowork, for example): paste the key into the conversation and ask the assistant to use it. set_api_key checks it with the API first. Where the app can show a confirmation form, you approve the account (its email and the key's last four characters) and the key is saved to the key file, readable only by your user. Where it can't, the key is kept for that session only and every result names the account. A saved key is never replaced without confirmation, and the tool never returns the key.

To avoid pasting the key each session, write the key file once yourself. Copy the key, then on macOS:

mkdir -p ~/.config/redact-pdf-mcp && chmod 700 ~/.config/redact-pdf-mcp && (umask 077 && pbpaste | tr -d '[:space:]' > ~/.config/redact-pdf-mcp/key) && chmod 600 ~/.config/redact-pdf-mcp/key

On Windows, in PowerShell:

$d = "$HOME\.config\redact-pdf-mcp"; New-Item -ItemType Directory -Force $d | Out-Null; (Get-Clipboard).Trim() | Set-Content -NoNewline "$d\key"

Tools

ToolWhat it does
redact_pdf_and_waitUpload, redact, wait and write the finished PDF. One call.
redact_pdfStart a job and return immediately, for several documents in parallel.
get_job_statusCheck a job: uploaded → analyzing → redacting → redacted or error.
download_redactedDownload the redacted output for one document.
download_correspondenceDownload the tag → original table of a pseudonymized document.
restore_namesPut the real names back into a .md, .txt or .docx file the assistant wrote. Returns the output path and counts, never a name.
try_demoNo key needed: redact the first page of a real file, or run a built-in sample.
get_account_statusCheck the key and see which account it belongs to.
set_api_keyCheck and save a key the user gives in the conversation (see above).

The redaction tools take mode (redact or pseudonymize), pii_categories, pii_included_terms (always redact), pii_excluded_terms (never redact) and retention. PDF, JPEG and PNG are accepted: pass a photo or a screenshot directly.

Anonymize, let the AI work, put the names back

  1. redact_pdf_and_wait with mode: "pseudonymize" writes the pseudonymized PDF and the correspondence table (*-correspondence.csv) next to the original, and returns document_text: the document as text with every name replaced by a tag such as [Person 1]. Past 32 KB the text is written to a file (document_text_path).
  2. The assistant writes its answer to a .md, .txt or .docx file and keeps the tags as written.
  3. restore_names with that file and the correspondence table writes <name>-restored.<ext> with the real names, and returns only the path and counts.

The assistant must not open the original, the correspondence table or the restored file: any of those reads puts the names back into the conversation. The server's instructions tell it so.

What runs where

  • The server runs on your computer and reads files only when a tool call names them.
  • Documents go to the Redact PDF AI API over TLS and are processed on Microsoft Azure in the EU (Ireland) and Switzerland. They are never used to train AI models.
  • The redacted PDF, the correspondence table and the restored file stay on your computer. restore_names uploads nothing.
  • No telemetry. The server makes only the API calls its tools describe.

Related pages