Omitly MCP

omitly-mcp

A Model Context Protocol server that exposes Omitly's local, verifiable PDF redaction to AI agents (Claude Code, Claude Desktop, and any other MCP client).

Repository scope and licence — please read before opening a PR.

This repository is source-available, not open source. See LICENSE:

the code is published so you can read exactly what runs on your machine before

you let it touch a confidential document. It is not licensed for reuse in other

projects.

It contains the MCP server and the compiled wasm detection bundle. The Omitly

redaction engine, the tamper-evidence seal and the licensing implementation are

not in this repository and are developed privately; this code calls the

engine, it does not contain it.

Development happens in a private repository and is mirrored here on release, so

pull requests cannot be merged. Issues and security reports are very welcome

— see SECURITY.md.

The point of difference: an agent can redact a document without uploading it anywhere. Redaction runs on-device through the Omitly engine and returns a signed audit log recording what was removed; the seal shows the delivered file is unchanged since it was sealed. It does not show that nothing else sensitive remains in the document — the opposite of pasting a confidential file into a chat model.

Five of the eleven tools (`find_sensitive_regions`, `locate_text`, `check_redaction`, `verify_redaction`, `extract_pdf_text`) work out of the box — `npm install`, no Rust toolchain, no native binary, no desktop app. They run on a wasm-bindgen build of the same detector that powers the web leak-checker at omitly.app, bundled directly in this package. create_pdf, the two write tools (redact_pdf, redact_by_entity), and the two seal-verification tools (verify_seal, verify_document) still need a configured native engine — see "Native engine" below. Neither seal tool has a wasm fallback yet: there is no wasm seal-verification path (tracked in issue #113), so both always require the native engine, even though checking a seal needs no licence.

Install

Add the server to your MCP client with npx — nothing to clone, build or compile. Published releases ship the wasm detector bundled, so a registry install never needs Rust.

Claude Code:

claude mcp add omitly --env OMITLY_ALLOWED_DIR=/path/agents/may/touch -- npx -y omitly-mcp

Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) and Windsurf (~/.codeium/windsurf/mcp_config.json) take the same entry:

{

"mcpServers": { "omitly": { "command": "npx", "args": ["-y", "omitly-mcp"], "env": { "OMITLY_ALLOWED_DIR": "/path/agents/may/touch" } } } }

Set OMITLY_ALLOWED_DIR to the folder holding the documents you want checked; without it the server uses the directory it was launched from (see "Access control"). Claude Desktop users can instead install the one-click .mcpb bundle (see "One-click install for Claude Desktop" below).

Five tools work out of the box. find_sensitive_regions and check_redaction are free but EVALUATION-marked and limited to 10 attempts a month, shared across the two, without a native engine (OMITLY_FREE_CAP changes the number); locate_text, verify_redaction and extract_pdf_text are free with no cap. Redaction (redact_pdf, redact_by_entity), create_pdf and seal verification need the native engine, which is not currently distributed outside the source repo (omitly#1405).

Skill (Claude Code)

The package ships a Claude skill at skill/SKILL.md: plain instructions that tell Claude when to reach for these tools and how to report results — masked values only, and what the free check does and does not prove.

Install it for Claude Code (user scope):

mkdir -p ~/.claude/skills/omitly-redaction

curl -fsSL https://raw.githubusercontent.com/omitly/omitly-mcp/main/skill/SKILL.md \ -o ~/.claude/skills/omitly-redaction/SKILL.md

A project can instead keep the skill under .claude/skills/omitly-redaction/. The skill is instructions only; limits and the free cap are enforced by the server, not by the skill.

Tools

Accept-in-app (omitly#1643)

While the Omitly desktop app is running on the same computer with Settings → Connect your AI → "Accept proposals in Omitly" on (the default), redact_pdf and redact_by_entity do not run: they return { status: "queued", proposalId } and the redaction becomes a proposal a person accepts or rejects in the app. On acceptance the desktop runs its own verified-removal engine, the survivor scan and the seal, and the sealed record says a person decided (human-desktop); this path needs no native engine on the agent's side. propose_redactions is the explicit form of the same thing; get_proposal_status follows the outcome; the person picks the output path in Omitly's own save dialog (outputPath is kept as the client's suggestion). Needs an omitly-mcp release that knows the channel — an older server writes directly. With no desktop running (or the toggle off), the write tools behave exactly as before and the record says mcp-agent (not human-reviewed). The two sides talk through files under the state directory (OMITLY_STATE_DIR, else ~/.omitly: desktop.json, proposals/, clients/) — no socket, no network. The PDF and the engine stay on this computer; text a client asks for (for example extract_pdf_text) goes to wherever that client's model runs.

PDF generation (create_pdf)

create_pdf is served by a separate binary, omitly-pdf, kept apart from the redaction engine because generation is a different trust model from verifiable redaction. It renders Markdown (or raw HTML) through a headless Chromium-family browser (Chrome/Chromium/Edge/Brave; override with OMITLY_BROWSER_BIN) — the same engine family the Omitly app's webview uses, so output looks printed rather than script-generated. It needs the native omitly-pdf binary, which is not currently distributed (omitly#1405) and whose source is not in this repository; point OMITLY_PDF_BIN at a copy to enable this tool.

// stdin

{ "command": "create", "outputPath": "/abs/out.pdf", "source": "# Hello\n\nBody markdown", "format": "markdown", "title": "Hello" } // stdout { "ok": true, "output": "/abs/out.pdf" }

Typical agent flows:

• Quick: `redact_by_entity` (find + redact + verify in one call).
• Careful: **find_sensitive_regions / locate_text → review → redact_pdf → verify_redaction*