yeaight7 Filesystem MCP Guardrails
When to use
Use when configuring, reviewing, or debugging a local filesystem MCP server — particularly when deciding which paths to expose, which methods to allow, and how to enforce workspace boundaries.
Safety Model
The core constraint is strict path bounding: the MCP server must only operate within explicitly declared workspace roots. No exceptions.
| Principle | Rule |
|---|---|
| Scope | Bind to the project workspace directory only — never /, ~, or OS dirs |
| Access | Start read-only; add write methods only when the use case requires them |
| Methods | Use an allowlist — block delete/move/rename by default |
| Secrets | Never expose .env, credential files, SSH keys, or token stores |
| Approval | Always require user approval before starting a new MCP server process |
Configuration Checklist
Before starting a filesystem MCP server:
- Allowed roots list is explicit and scoped to the project directory.
- No root is set to
/,~, or any system-level path. - Method allowlist is defined (e.g.,
read_file,list_directory,search_files). - Destructive methods (
delete_file,move_file,write_file) are explicitly enabled only if required. - Sensitive file patterns are excluded:
*.env,*.key,*.pem,*secrets*,.ssh/. - Server timeout is set (avoid hanging processes).
- Log output does not include file contents — only paths and operation results.
Workflow
- Define scope — identify which directories the agent legitimately needs to access for this task.
- Set roots — configure the server with the narrowest possible root list (usually just the project root).
- Define allowlist — start with read-only methods; add write methods only after explicit use-case review.
- Validate path boundaries — test that requests for paths outside the declared roots are refused with a clear error.
- Verify cleanup — confirm the server process exits cleanly when the session ends; no background processes left running.
Out-of-Root Path Refusal
The server must return a clear error for any request targeting a path outside declared roots:
Error: path '/etc/passwd' is outside allowed workspace root '/home/user/project'
Silent failures or fallback to broader access are not acceptable.
Safety Constraints
- Never configure MCP servers with root or wide-ranging access.
- Do not start a filesystem MCP server without explicit user approval for the scope.
- Prefer read-only operations until write need is explicit and scoped.
- Do not log configured roots in a way that exposes sensitive path contents.
- On Windows: validate boundary behavior with both forward-slash and backslash paths.
Validation / Done Criteria
- Allowed roots are listed and scoped to the workspace.
- Out-of-root path requests are refused with a clear error.
- Method allowlist is explicit; destructive methods are not in the default list.
- Server process exits cleanly after session ends.
References
references/path-boundary-checklist.md