CloakMCP

CloakMCP

Your secrets stay home. The AI only sees tags.

Local-first secret sanitization before LLM exposure — works with any LLM, includes first-class Claude Code integration

[](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://pypi.org/project/cloakmcp/) [](https://github.com/ovitrac/CloakMCP/releases) [](./tests) [](#mcp-tool-server--6-tools) [](https://deepwiki.com/ovitrac/CloakMCP) [](https://github.com/psf/black)

[See It Work](#see-it-work) • [Features](#features) • [Quick Start](#quick-start) • [Claude Code Integration](#claude-code-integration) • [Demo](#live-demo) • [Security](#security-architecture) • [Documentation](#documentation)

---

See It Work

Every time you paste code into an LLM, your secrets go with it:

private static final String API_KEY  = "sk_live_51Jd9RealKeyGoesHere";
private static final String DB_PASS  = "P@ssw0rd-Pr0duction!";
private static final String AWS_KEY  = "AKIAIOSFODNN7REALKEY1";

CloakMCP intercepts — automatically, invisibly — before the LLM ever sees your code:

 YOUR MACHINE                              LLM (Claude, Codex, Copilot…)
 ────────────                              ──────────────────────────────

 API_KEY = "sk_live_51Jd9RealKey"          API_KEY = "TAG-d7182d9e703d"
 DB_PASS = "P@ssw0rd-Pr0duction!"         DB_PASS = "TAG-a6c0cd73627c"
 AWS_KEY = "AKIAIOSFODNN7REALKEY1"         AWS_KEY = "TAG-f63caf98581a"

The LLM understands the code perfectly — it just can't see the secrets:

 You → LLM:      "Which variable stores the database password?"

 LLM:            "DB_PASS on line 27 stores the credential TAG-a6c0cd73627c.
                  It's used in the JDBC connection to the PostgreSQL instance."

 You → CloakMCP: cloak unpack

 Result:          TAG-a6c0cd73627c → P@ssw0rd-Pr0duction!   ← restored locally

The LLM identified the right variable, understood the architecture, explained the data flow — but the actual password never left your machine. One command brings it back. This works with Claude, Copilot, Codex, Gemini, local Ollama models — any LLM that reads your code.

With Claude Code, the entire cycle is automatic via hooks: secrets vanish at session start, reappear at session end. Zero human intervention.

---

Overview

CloakMCP is a local-first, deterministic sanitizer that removes or neutralizes secrets (emails, IPs, URLs, tokens, API keys, SSH keys, JWTs) before your text/code reaches any LLM — Claude, GitHub Copilot, OpenAI Codex, Gemini, or local models via Ollama. The core CLI (cloak pack/unpack/scan/sanitize) is LLM-agnostic; a dedicated Claude Code integration provides automatic session-level protection via hooks and an MCP tool server.

What makes CloakMCP different

| Feature | CloakMCP | ggshield / gitleaks | SOPS | DIY Scripts | |---------|----------|---------------------|------|-------------| | Detect secrets | Yes | Yes | No | Yes | | Reversible redaction | Yes | No | No | No | | LLM-optimized workflow | Yes | No | No | No | | MCP tool server | Yes (6 tools) | No | No | No | | IDE hook integration | Yes (Claude Code auto pack/unpack) | No | No | No | | Deterministic tags | Yes (HMAC-based) | No | No | Varies | | Local-only vault | Yes | No | No (cloud KMS) | Varies | | Directory pack/unpack | Yes | No | No | No | | Encrypted storage | Yes (AES-128 Fernet) | No | Yes (cloud KMS) | Varies | | IDE integration | Yes (VS Code) | Yes | No | No |

Key Capabilities

• LLM-agnostic: Core CLI works with any LLM workflow — no vendor lock-in
• Local-first: All operations run on your machine — no cloud dependencies
• Reversible: Deterministic tagging allows safe restoration via encrypted vaults
• Batch processing: Pack/unpack entire codebases with one command
• Policy-driven: Configure detection rules via YAML (regex, entropy, IPs, URLs)
• Group policies: Hierarchical policy inheritance (company → team → project)
• Auditable: Every operation logged to audit/audit.jsonl
• Claude Code integration: Hooks automate pack/unpack at session boundaries; 6 MCP tools for in-session use

---

Claude Code Integration

> CloakMCP's core CLI is LLM-agnostic. This section describes the first-class integration with Claude Code, which automates the pack/unpack lifecycle through hooks and exposes tools via the Model Context Protocol (MCP). For other LLMs, use cloak pack / cloak unpack manually or in your own scripts.

CloakMCP integrates with Claude Code through two complementary mechanisms:

1. Hooks — Automatic Session Protection

When Claude Code starts a session, CloakMCP automatically packs all files. When it ends, it automatically unpacks. Zero manual steps.

 Claude Code starts  →  SessionStart hook  →  cloak pack   (secrets → tags)
 Claude works on code →  MCP tools available (6 tools)
 Claude Code exits   →  SessionEnd hook    →  cloak unpack (tags → secrets)

Install (cross-platform, no bash required):

cloak install                          # secrets-only profile (default)
cloak install --profile hardened       # + Bash safety guard + read guard
cloak install --dry-run                # preview without changes

Configuration (.claude/settings.local.json — auto-generated by cloak install):

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{"type": "command", "command": "cloak hook session-start"}]
    }],
    "SessionEnd": [{
      "hooks": [{"type": "command", "command": "cloak hook session-end"}]
    }],
    "UserPromptSubmit": [{
      "hooks": [{"type": "command", "command": "cloak hook prompt-guard"}]
    }],
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{"type": "command", "command": "cloak hook guard-write"}]
    }]
  }
}

The UserPromptSubmit guard scans every user message for secrets — blocking critical/high and warning on medium/low. The PreToolUse guard scans content Claude tries to write — and denies if raw secrets appear in generated code. The hardened profile adds a Read|Grep|Glob guard that blocks access to backup directories and session state files.

2. MCP Tool Server — 6 Tools

CloakMCP exposes tools via the Model Context Protocol. The recommended approach uses the FastMCP-based cloak serve command (stdio by default, optional SSE/streamable-http). Any MCP-compatible client (Claude Code, Claude Desktop, or custom agents) discovers them automatically:

| Tool | Description | |------|-------------| | cloak_scan_text | Scan text for secrets (returns matches without modifying) | | cloak_pack_text | Replace secrets with vault tags in text | | cloak_unpack_text | Restore vault tags to original secrets | | cloak_vault_stats | Get vault statistics (total secrets, unique tags) | | cloak_pack_dir | Pack entire directory | | cloak_unpack_dir | Unpack entire directory |

Configuration (.mcp.json):

{
  "mcpServers": {
    "cloakmcp": {
      "type": "stdio",
      "command": "cloak",
      "args": ["serve"]
    }
  }
}

> Note: cloak serve auto-discovers .cloak/policy.yaml (set via cloak policy use). You can also pass --policy explicitly.

Network transport (SSE on port 8766):

cloak serve --transport sse --port 8766

> Note: cloak serve requires the optional MCP dependency: pip install cloakmcp[mcp]. > The legacy cloak-mcp-server entry point (raw JSON-RPC) remains available without extra dependencies.

---

Features

Detectors

| Type | Examples | Action | |------|----------|--------| | AWS keys | AKIA*, ASIA* | block | | JWT tokens | 3-part base64 | pseudonymize | | SSH private keys | PEM blocks | replace | | X.509 certificates | PEM blocks | block | | Email addresses | with whitelist support | replacewithtemplate | | URLs | HTTP/HTTPS (internal) | pseudonymize | | IP addresses | IPv4/IPv6 with CIDR whitelists | pseudonymize | | High-entropy strings | base64-like tokens | redact | | Custom regex | user-defined patterns | configurable |

Actions

| Action | Behavior | Reversible | |--------|----------|------------| | block | Refuse to process (exit with error) | — | | redact | Replace with ` | No | | pseudonymize | Replace with HMAC-based token (TAG-xxxxxxxxxxxx) | Yes (vault) | | hash | Replace with SHA-256 hash | No | | replacewithtemplate | Custom template (e.g., ) | No | | allow` | Keep unchanged (whitelist) | — |

CLI Commands

| Command | Description | |---------|-------------| | cloak scan --policy POL --input FILE | Scan file, log detections (no modification) | | cloak sanitize --policy POL --input FILE --output OUT | Sanitize a single file (one-shot) | | cloak pack --policy POL --dir DIR | Replace secrets by deterministic tags across directory | | cloak unpack --dir DIR | Restore original secrets from local vault | | cloak policy validate --policy POL | Validate policy file (including inheritance chain) | | cloak policy show --policy POL | Show merged policy after inheritance resolution | | cloak policy use | Set per-project policy (copies to .cloak/policy.yaml); --show, --clear, --link, --force | | cloak policy reload | Reload policy mid-session (G2): re-resolve, update pinned hash, print diff | | cloak sanitize-stdin --policy POL | Sanitize text from stdin to stdout (pipe helper) | | cloak repack --dir DIR --policy POL | Incremental re-pack: scan new/changed files only | | cloak verify --dir DIR | Post-unpack verification: scan for residual tags | | cloak status --dir DIR | Session diagnostics: state, manifest, delta, vault, tags, backups, audit | | cloak restore --dir DIR | Restore secrets from vault (default) or --from-backup --force | | cloak hook | Hook handler for Claude Code integration (session-start, session-end, guard-write, guard-read, prompt-guard, safety-guard, audit-log) | | cloak install | Cross-platform hook installer; --profile, --method cli\|copy\|symlink, --policy, --dry-run, --uninstall | | cloak hooks-path | Print path to bundled hook scripts; --format sh\|py\|cli (toolbox discovery contract) | | cloak doctor | Installation health check: platform, hook method, policy, vault state | | cloak key wrap | Wrap key with passphrase (Tier 0 → Tier 1); requires CLOAK_PASSPHRASE | | cloak key unwrap | Unwrap key back to raw format (Tier 1 → Tier 0) | | cloak backup migrate | Encrypt legacy plaintext backups; --dry-run, --quarantine | | cloak backup prune | Remove old backups; --ttl 30d, --keep-last 10, --apply, --include-legacy | | cloak serve | FastMCP server: stdio (default), SSE, or streamable-http transport | | cloak serve --check | Validate MCP server configuration and exit | | cloak --version | Print CloakMCP version | | cloak-mcp-server | Legacy MCP tool server (JSON-RPC 2.0 over stdio) |

---

Live Demo

The demo/ directory contains a realistic Spring Boot banking microservice with 10+ fake secrets across 3 config files. Four demo scripts showcase different aspects:

LLM Demo — The Highlight

Packs the code, asks a real LLM to explain it, proves the AI understands the logic without seeing secrets:

cd demo && bash llm_demo.sh              # auto-detect (Ollama / Claude)
cd demo && bash llm_demo.sh --ollama     # force local Ollama
cd demo && bash llm_demo.sh --claude     # force Claude Code CLI

Sample output — Qwen2.5-coder explains cloaked banking code

▶ Asking Ollama (qwen2.5-coder:14b) to explain the cloaked code...

  This class simulates a high-value transfer workflow in a banking service.
  It initiates the transfer by performing risk and compliance checks,
  creating a transfer intent, signing it, and calling a payment gateway.
  The process involves persisting data to a database, sending confirmation
  emails, notifying operations via a webhook, and archiving an audit trail.

The LLM understood 8 workflow steps, compliance logic, and integrations
— zero real credentials seen.

MCP Protocol Demo

Shows CloakMCP as an MCP tool server with raw JSON-RPC protocol:

cd demo && bash mcp_demo.sh              # raw JSON-RPC protocol (5 steps)
cd demo && bash mcp_demo.sh --claude     # + full hook lifecycle with live LLM

With --claude, demonstrates the complete transparent lifecycle:

1. SessionStart hook fires → cloak pack (automatic)
2. An LLM explains the cloaked code — sees only TAG-xxxx tokens
3. SessionEnd hook fires → cloak unpack (automatic)

Other Demos

cd demo && bash transcript.sh            # screenshot-friendly before/after (6 phases)
cd demo && bash run_demo.sh              # interactive 5-act presentation

Full demo documentation: See [demo/README.md](demo/README.md)

---

Quick Start

> New to CloakMCP? See the full [Quickstart Guide](docs/QUICKSTART.md) with FAQ, compatibility matrix, and troubleshooting.

1. Install

From PyPI (recommended):

pipx install cloakmcp              # isolated install, cloak available globally
# or
pip install cloakmcp               # into current environment
pip install cloakmcp[mcp]          # optional: enables cloak serve (FastMCP)

From source (development):

git clone https://github.com/ovitrac/CloakMCP.git && cd CloakMCP
pip install -e ".[mcp]"

> Vault keys are auto-generated on first use — no manual key setup required.

2. Set Policy (Recommended)

# Set per-project policy (persists in .cloak/policy.yaml)
cloak policy use examples/mcp_policy.yaml

# Verify
cloak policy use --show

3. Pack / Unpack (Works with Any LLM)

# Pack: replace secrets with tags (vaulted, reversible)
cloak pack --policy examples/mcp_policy.yaml --dir . --prefix TAG

# Now safe to share with any LLM — secrets replaced with TAG-xxxxxxxxxxxx
# Vault stored in ~/.cloakmcp/vaults/

# Unpack: restore original secrets
cloak unpack --dir .

4. Claude Code Setup (Optional)

If you use Claude Code, the pack/unpack cycle is fully automated via hooks:

# The repo already includes .mcp.json and .claude/hooks/
# Just start Claude Code in the project directory:
claude

# CloakMCP hooks fire automatically:
#   SessionStart → pack (secrets hidden)
#   SessionEnd   → unpack (secrets restored)

---

Security Architecture

How CloakMCP Protects Your Secrets

graph TB
    subgraph "Your Local Machine"
        A[Original Codewith Secrets] -->|cloak pack| B[Packed Codewith Tags]
        B --> C[Git Repository]
        A -->|secrets extracted| D[Encrypted Vault~/.cloakmcp/vaults/]
        D -.encryption key.-> E[Encryption Key~/.cloakmcp/keys/]
    end

    subgraph "Shared with LLM"
        C -->|safe to share| F[Claude/Codexsees only tags]
    end

    subgraph "Restoration"
        F -->|modified code| G[Code with Tags]
        G -->|cloak unpack| H[Original Codesecrets restored]
        D -.decryption.-> H
    end

    style D fill:#ffcccc, color:#000000
    style E fill:#ffcccc, color:#000000
    style F fill:#ccffcc, color:#000000
    style H fill:#ccccff, color:#000000

Why LLMs Cannot Access Secrets

The sequence below shows the automated Claude Code hook flow. For other LLMs, the developer runs cloak pack / cloak unpack manually — the security properties are identical.

sequenceDiagram
    participant Dev as Developer
    participant Cloak as CloakMCP
    participant Vault as Encrypted Vault(~/.cloakmcp/)
    participant LLM as LLM (any)

    Note over Dev,Cloak: cloak pack (or SessionStart hook)
    Dev->>Cloak: cloak pack --dir .
    Cloak->>Cloak: Scan for secrets
    Cloak->>Vault: Store secret → TAG mapping (encrypted)
    Cloak->>Dev: Files now contain tags (TAG-xxxx)

    Dev->>LLM: Work on tagged code
    Note over LLM: LL

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ovitrac](https://github.com/ovitrac)
- **Source:** [ovitrac/CloakMCP](https://github.com/ovitrac/CloakMCP)
- **License:** MIT

Install and usage instructions live in the source repository linked above.