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

Category	Patterns	Examples
Prompt injection	13	Instruction override, role hijacking, hidden instructions, multilingual injection (10 languages)
Command injection	6	Shell metacharacters, dangerous commands, sensitive file access
Data exfiltration	6	URL exfil, DNS exfil, encoded exfil
Secret detection	24	AWS, GitHub, Slack, Stripe, OpenAI, JWT, private keys, connection strings
PII detection	7	Email, phone, SSN, credit card, IPv4, Korean resident ID, Korean phone

Security infrastructure

Feature	Description
Rug-pull detection	SHA-256 hash pinning of tool descriptions, persisted to SQLite
Server schema pinning	TOFU-based pinning. Detects tool addition, removal, and schema drift
Context budget	Configurable max response size with warn/truncate/block actions
Policy engine	Tool-level allow/deny with glob patterns and argument validation
OPA integration	External policy via Open Policy Agent with SSRF protection and fail-closed
Data flow policies	Cross-server session-level tool call tracking (e.g. deny read_file → send_email)
JWT authentication	HS256, RS256, JWKS rotation for SSE/HTTP transports
Audit logging	SQLite with secret masking, HMAC-SHA256 tamper detection, auto-pruning
SARIF output	Export findings for GitHub Security tab integration
Remediation guidance	Every finding includes actionable fix advice

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

ID	Risk	v1.0	How
MCP01	Token/Secret Exposure	Yes	Secret pattern detection + audit log masking
MCP02	Tool Poisoning	Yes	Tool description hash pinning (rug-pull detection)
MCP03	Excessive Permissions	Yes	Policy engine with tool allow/deny + argument constraints
MCP04	Command Injection	Yes	Command injection patterns in detection engine
MCP05	Insecure Data Handling	Yes	Secret masking, HMAC integrity chain, DB size limits
MCP06	Insufficient Logging	Yes	SQLite audit log + SARIF export + HMAC tamper detection
MCP07	Insufficient Auth	Yes	JWT authentication (HS256/RS256/JWKS) for HTTP transports
MCP08	Server Spoofing	Yes	Server schema TOFU pinning (SRV-001/002/003)
MCP09	Supply Chain Compromise	Partial	Runtime behavior inspection; no package-level verification
MCP10	Context Injection	Yes	Context budget + bidirectional injection scanning

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.

Variable	Values	Description
MCP_FENCE_MODE	monitor, enforce	Operation mode
MCP_FENCE_LOG_LEVEL	debug, info, warn, error	Log verbosity
MCP_FENCE_JWT_SECRET	string	Shared secret for HS256 JWT

---

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

Flag	Default	Description
-c, --config <path>		Config file path
-m, --mode <mode>	monitor	monitor or enforce
--log-level <level>	info	debug, info, warn, error
-t, --transport <type>	stdio	stdio, sse, http
-p, --port <port>	3000	Listen port (SSE/HTTP)
-u, --upstream <url>		Upstream server URL (SSE/HTTP)
--jwks-url <url>		JWKS endpoint for RS256 key rotation

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

Version	Focus	Status
v0.1	stdio proxy, bidirectional scanning, secret detection, hash pinning, policy engine, audit, CLI	Done
v0.2	Audit hardening (masking, HMAC, pruning, verify), Unicode normalization	Done
v0.3	SSE + HTTP transport, JWT auth, OPA integration, data flow policies	Done
v0.4	Server schema TOFU pinning, context budget, SQLite-persisted hash pins	Done
v1.0	PII detection, remediation guidance, 9 security hardening fixes	Current
v1.x	ML-based semantic detection, session-level multi-step analysis	Planned

---

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