A filesystem MCP tool is not harmless because it is local or read-only.
It is authority over host state, repo state, secret-bearing paths, and sometimes customer data.
The production question is not whether the schema accepts a path string. It is whether the runtime can prove the final path stayed inside the intended workspace before host state reaches the agent.
Fast answer
- A model-supplied path is an authorization input. Treat it that way before any read, list, search, summarize, diff, patch, write, delete, execute, or upload runs.
- The boundary has to be proven at runtime: resolve cwd, normalize the requested path, canonicalize through symlinks, compare against the allowed root, and deny neighboring paths with typed receipts.
- Scanner findings and schema lint are useful tripwires. Production proof is a paired fixture: one allowed file operation and one denied sibling, parent traversal, hidden config, symlink escape, or host-mount target through the same endpoint and trace path.
- If the receipt cannot show requested path, canonical path, allowlist decision, symlink policy, redaction rule, caller, workspace, and operation class, the route is not ready for repeat agent use.
Operator rule
A denied sibling path is positive evidence.
The useful proof is not that the happy-path file opened. It is that a nearby unsafe path failed closed with a receipt the operator can audit after the agent moves on.
The production checklist
1. Operation class gate
Separate read, list, search, summarize, diff, patch, write, delete, execute, and upload. A route approved for read does not inherit write, patch, or command authority.
2. cwd and workspace anchor
Record the runtime cwd, workspace id, repo id, branch/ref if applicable, and the intended allowed root before interpreting any model-supplied path.
3. Canonical path proof
Normalize the requested path, resolve relative segments, follow or reject symlinks according to policy, and compare the final canonical path to the allowed prefix.
4. Denied-neighbor fixtures
Test parent traversal, sibling workspaces, hidden config, lockfiles, credentials, host mounts, generated artifacts, and write targets outside policy under the same caller and endpoint.
5. Output redaction and shape
Bound file size, match allowlisted extensions or globs, redact secrets/topology/customer data, and return typed artifacts or summaries instead of dumping unbounded content into context.
6. Typed denial receipt
Return a policy denial that includes requested path, canonical path or resolution failure, operation class, rule id, caller/workspace, and recovery hint.
Denied neighbors
Pair every allowed file with the path class that must fail closed.
Parent traversal
Examples: ../, ..%2f, nested symlink to parent, absolute path fallback.
Expected: Deny before read/write. The receipt names normalized path, canonical path decision, and allowed-root rule.
Sibling workspace or repo
Examples: ../other-customer, ../repo-b, /Volumes/shared/adjacent-project.
Expected: Deny unless a separate route card explicitly names that workspace and caller. Same agent identity is not enough.
Hidden config and credentials
Examples: .env, .npmrc, .aws/credentials, SSH keys, token caches, local browser/session files.
Expected: Deny or redact by default. The receipt shows the secret-bearing class protected and the allowed recovery path.
Host mount or system path
Examples: /etc, /proc, /var/run/docker.sock, host-mounted volumes, CI workspace parents.
Expected: Deny as host-state authority unless a reviewed admin route exists with expiration, receipt, and blast-radius owner.
Trace evidence
The receipt has to prove which host state stayed unreachable.
Filesystem containment is only operator-grade if the decision is reconstructable. Store enough evidence to show the path was normalized, resolved, classified, and blocked or allowed before content, secrets, or write authority reached the agent.
The receipt should include:
- caller / tenant / workspace
- tool route and operation class
- runtime cwd and allowed root
- requested path and raw input
- normalized path
- canonical path or resolution error
- symlink and mount decision
- matched allowlist / deny rule
- file size and extension / glob class
- redaction policy applied
- credential lane or host resource protected
- policy decision and denial code
- receipt id and recovery hint
Copy-paste route card
Repo-wide access is a different route, not an escalation after failure.
Filesystem route:
Caller / workspace allowed:
Allowed root / repo / branch:
Allowed operation class:
Allowed glob / extension / size:
Symlink and mount policy:
Redaction rule:
Forbidden neighboring paths:
Credential / host resource protected:
Receipt fields:
Expiration / re-review date:
Some agents legitimately need broader repository context. That does not make every path in the workspace fair game. Give each filesystem lane its own caller, operation class, allowed root, redaction rule, denied neighbors, and expiration.
Common misreads
Filesystem safety usually collapses in predictable places:
- Calling a file read safe because the tool cannot write, while it can still expose secrets, private repos, host topology, customer data, or prompts.
- Validating the path string but not the canonical path after cwd, symlinks, mount points, case behavior, and relative segments resolve.
- Allowing repo access as a blanket instead of separating source files, generated artifacts, hidden config, lockfiles, scripts, and credential stores.
- Letting a denied read retry through search, glob, summarize, archive, or upload helpers that do not share the same filesystem policy.
- Logging only a generic file-not-found or permission error instead of a typed policy receipt that proves the unsafe neighbor was blocked.
- Treating scanner badges as proof instead of keeping allowed and denied runtime fixtures in the promotion gate.
Related operator guides
- MCP Server Quality Signals for Agents
- How to Evaluate MCP Servers
- MCP Threat Model Template for Agent Tools
If you want help hardening one filesystem route card, start here: MCP Route Hardening Checklist.
Top comments (0)