mcp-gate

A path is a request. The roots boundary is the guarantee.

An MCP file-access server enforces which files a model may touch through roots — a set of authorized directories. mcp-gate demonstrates the difference between telling the server to stay inside its roots and enforcing it: the same attack suite is run against a version that only has an instruction, and a version that canonicalizes every path and checks it against the boundary before any read. One leaks; one holds. Both directions are enforced in CI.

This is an independent implementation of concepts from Anthropic's advanced MCP material, written to showcase three things explicitly:

How it works

flowchart TD
    C[MCP client / model] -- "read_file(path)" --> S[FastMCP server]
    S --> M{mode}

    M -- prompt --> I["system prompt says: stay inside roots"]
    I --> O1[open path as given]
    O1 --> L["LEAK: out-of-bounds secret served"]

    M -- boundary --> D["1. unquote — defuse %2e%2e"]
    D --> A["2. abspath + realpath — collapse .. and follow symlinks"]
    A --> R{"3. inside an authorized root?"}
    R -- yes --> F[open file] --> OK[served]
    R -- no --> X["AccessError: path escapes authorized roots"]
    X --> LOG["ctx.info log + progress notification"]

    subgraph EVAL["eval suite — both halves must hold"]
        AT["5 attacks: direct, ../, absolute, symlink, %2e"] --> B1["boundary_no_escape = 1.0"]
        AT --> B2["prompt_escape_demonstrated = 1.0"]
        B1 & B2 --> CI{CI}
        CI -- "0 escapes AND leak still shown" --> PASS[PASS]
        CI -- "either fails" --> FAIL["FAIL: vacuous or broken"]
    end

The prompt lane is a worst-case control on purpose: if it ever stops leaking, the "secure" result proves nothing, so CI fails on that too.

Related MCP server: personal-mcp-bridge

The two modes

The attack suite

direct_ask succeeding in both modes is the deceptive part: a quick manual test of prompt-layer security looks safe, then fails under an attack you didn't try.

The gate (CI-enforced, both directions)

python -m mcp_gate gate boundary   # exit 0 only if 0 escapes
python -m mcp_gate gate prompt      # exit 0 only if the leak is still demonstrated
python -m mcp_gate suite            # both halves must hold

gate prompt failing to leak would mean the demo has gone vacuous (the "secure" result is meaningless if the insecure one also passes), so CI treats that as a build failure too.

Quickstart

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

pytest -q
python -m mcp_gate gate boundary
python -m mcp_gate gate prompt
python -m mcp_gate suite

Run the live MCP server + client demo (needs pip install -e ".[demo]" and an ANTHROPIC_API_KEY in your environment for the sampling tool):

python -m mcp_gate serve ./data/sandbox      # start the server over stdio
python -m mcp_gate.client ./data/sandbox     # drive it: logs, progress, sampling, a blocked attack

See RESULTS.md for captured output — every block there is real command output, regenerated by scripts/make_results.py, never hand-edited.

Notes

• All data under data/ is fictional; data/out_of_bounds/secret.txt is a labeled stand-in for "a file the server must never serve."

• Part of the -gate family: nothing ships until it passes a gate.