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:

Capability	Where it shows up
Advanced MCP server	src/mcp_gate/server.py — a FastMCP server exposing typed tools (list_roots, read_file, list_dir, summarize_file), with structured errors and server-initiated sampling (ctx.session.create_message) so the server can ask the client to run the model.
Logs & progress	Every tool streams MCP logging notifications (ctx.info) and progress (ctx.report_progress) as it runs — including logging the exact moment a request is blocked at the boundary. src/mcp_gate/client.py shows the matching logging_callback / sampling_callback.
Access control	src/mcp_gate/boundary.py — the guarantee: .. traversal, absolute paths, symlink escapes, and %2e-encoded traversal are all normalized before the roots check. This is the gate.

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.

The two modes

Mode	How it decides	Result
prompt (insecure control)	A system-prompt instruction says "only read files under the roots," but the path is opened as given.	Leaks — the naive path-handler is a worst-case control, on purpose.
boundary (enforced)	Each path is decoded, realpath-resolved (collapsing .. and following symlinks), then required to sit inside an authorized root.	Holds — out-of-bounds requests are refused before any file is opened.

The attack suite

Attack	prompt mode	boundary mode
direct_ask (a legitimate in-root file)	served ✓	served ✓
dotdot_traversal (../out_of_bounds/secret.txt)	leaks	blocked
absolute_path (absolute path to the secret)	leaks	blocked
symlink_escape (a symlink inside the sandbox → outside)	leaks	blocked
encoded_traversal (%2e%2e/...)	leaks	blocked

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.