mcp-fence

A security proxy for MCP servers — sits between your AI agent and MCP server, scanning both requests AND responses for prompt injection, secret leaks, and tool tampering.

Why mcp-fence?

MCP servers return data that AI agents trust blindly. A compromised server can embed hidden instructions in its responses, leak secrets through tool outputs, or silently change what a tool does after you've approved it.

Most MCP security tools only scan the input side. mcp-fence scans both.

• Bidirectional scanning — catches threats hiding in server responses, not just requests
• Rug-pull detection — pins tool descriptions by hash. If a server silently changes what a tool does, mcp-fence flags it immediately
• Zero config — works out of the box in monitor mode. Logs threats without blocking, so you never break a working setup

Who needs this?

You probably do if:

• You connect to MCP servers you don't fully control
• You let AI agents read files, call tools, or access secrets
• You assume server responses are "just data"

Quick Start

1. Try it now

npx mcp-fence start -- npx @modelcontextprotocol/server-filesystem /tmp

That's it. mcp-fence sits between your client and server, scanning every message in real time. Default is monitor mode — logs findings without blocking, so nothing breaks.

2. Claude Desktop

Add mcp-fence as a wrapper in your claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "mcp-fence",
        "start",
        "--mode", "enforce",
        "--",
        "npx", "@modelcontextprotocol/server-filesystem", "/tmp"
      ]
    }
  }
}

Your MCP server works exactly as before. mcp-fence just inspects traffic passing through.

3. SSE / Streamable HTTP

# Proxy a remote MCP server over SSE
mcp-fence start --transport sse --upstream http://localhost:8080 --port 3000

# Streamable HTTP with JWT authentication
MCP_FENCE_JWT_SECRET=my-secret mcp-fence start \
  --transport http --upstream http://localhost:8080 --port 3000

4. Standalone scan (no proxy needed)

# Scan a file
mcp-fence scan ./suspicious-prompt.txt

# Scan inline text
mcp-fence scan --text "ignore all previous instructions"

# Scan as a server response
mcp-fence scan ./response.json --direction response

Architecture

                        mcp-fence
                  ┌─────────────────────┐
[MCP Client] ──> │  1. Detection Engine │ ──> [MCP Server]
          stdio / │  2. Hash Pin Check   │ stdio / SSE /
          SSE /   │  3. Policy Engine    │ Streamable HTTP
          HTTP    │  4. Context Budget   │
[MCP Client] <── │  5. Audit Logger     │ <── [MCP Server]
                  └─────────────────────┘
                           │
                     [SQLite Audit DB]

Every message flows through the same pipeline:

1. Intercept — Proxy captures the JSON-RPC message (request or response)
2. Detect — Injection, secret, PII, and command-injection patterns
3. Pin check — For tools/list responses, flags any description or schema changes
4. Policy — Tool-level allow/deny rules, argument constraints, OPA decisions
5. Context budget — Response size limits (warn/truncate/block)
6. Audit — Every result logged to SQLite with HMAC integrity chain
7. Forward or block — Monitor mode passes everything; enforce mode rejects threats

Modules are decoupled: detection doesn't import policy, audit doesn't import detection. The proxy orchestrates through the ScanResult contract.

Features

Detection

Security infrastructure

Limitations

• Detection is regex-based. Known patterns are caught, but novel injection via paraphrase or synonyms will pass through. ML-based semantic detection is planned for v1.x.
• TOFU pinning trusts on first observation. If the first contact is already compromised, it won't be detected.
• MCP09 (Supply Chain) is only partially covered — runtime behavior inspection catches post-compromise activity, but there's no package-level verification.
• Large responses are scanned at the head and tail only. Content in the middle of very large messages may not be inspected.

Full threat model: THREAT_MODEL.md

OWASP MCP Top 10 Coverage

CVE coverage: Tested against 44 known MCP vulnerabilities (13 specific CVEs) across 86 attack scenarios with 86% detection rate. Remaining 14% are server-implementation flaws outside proxy scope.

Or install globally:

npm install -g mcp-fence

Configuration

Generate a config file:

mcp-fence init

This creates fence.config.yaml:

# Operation mode: "monitor" (log only) or "enforce" (block threats)
mode: monitor

log:
  level: info

detection:
  warnThreshold: 0.5
  blockThreshold: 0.8
  maxInputSize: 10240

policy:
  defaultAction: allow
  rules:
    - tool: "exec_cmd"
      action: deny
    - tool: "read_file"
      action: allow
      args:
        - name: path
          denyPattern: "^\\.env$|^/etc/"
    - tool: "write_*"
      action: deny

# jwt:
#   enabled: true
#   audience: "mcp-fence"
#   issuer: "my-auth-server"

# dataFlow:
#   enabled: true
#   rules:
#     - from: "read_file"
#       to: "send_email"
#       action: deny

# contextBudget:
#   enabled: true
#   maxResponseBytes: 102400
#   truncateAction: warn

Config priority: CLI flags > environment variables > YAML file > defaults.

CLI Reference

start — Run the security proxy

mcp-fence start -- npx @modelcontextprotocol/server-filesystem /tmp
mcp-fence start --mode enforce --config ./fence.config.yaml -- node my-server.js
mcp-fence start --transport sse --upstream http://localhost:8080 --port 3000

scan — Standalone threat scan

mcp-fence scan ./file.txt
mcp-fence scan --text "ignore all previous instructions"
mcp-fence scan ./response.json --direction response
mcp-fence scan ./file.txt --format sarif > results.sarif

logs — Query the audit trail

mcp-fence logs --since 1h --level warn
mcp-fence logs --format sarif > audit.sarif
mcp-fence logs --direction response --limit 50

verify — Check audit log integrity

mcp-fence verify

init — Generate default config

mcp-fence init
mcp-fence init --output ./custom-config.yaml

status — Show config and capabilities

mcp-fence status

Programmatic Usage

mcp-fence exports its detection engine, policy engine, and audit logger as importable modules. See the source code in src/ for available APIs.

Roadmap

Contributing

Contributions welcome. Please open an issue before submitting large changes.

git clone https://github.com/yjcho9317/mcp-fence.git
cd mcp-fence
npm install
npm test
npm run typecheck
npm run lint

Security vulnerabilities: please report via THREAT_MODEL.md. Do not open public issues for security bugs.

Security-critical modules (src/detection/, src/integrity/, src/policy/local.ts) require manual review on every PR. No exceptions.

License

MIT