How to Configure Scoped Filesystem Access for AI Agents

AI agents running on your machine have filesystem access through your user account permissions. Without proper scoping, a compromised agent—or even an overly helpful one—can read sensitive files or make destructive changes to directories you never intended to expose.

Quick Answer: Configure scoped filesystem access by explicitly declaring which directories each agent can access. For MCP servers, pass allowed paths as command arguments. For Claude Code, use `additionalDirectories` in settings.json. For Cursor, use `.cursorignore` and sandbox profiles. For Codex, set `sandbox_mode = "workspace-write"`. For maximum isolation, run agents in Docker Sandboxes or microVMs. Always follow the principle of least privilege: default deny, explicitly allow only what's needed.

What is scoped filesystem access?

Scoped filesystem access restricts an AI agent to specific directories rather than granting full filesystem privileges. Instead of an agent having access to your entire home directory or system root, you explicitly define boundaries—perhaps /projects/repo-a for one agent and /notes (read-only) for another.

This approach implements the security principle of least privilege: agents get only the minimum access required for their task.

Why does scoped access matter for AI agents?

A compromised agent skill runs with whatever permissions the agent holds—terminal access, file system access, and stored credentials. Research from BlueRock Security found that 36.7% of MCP servers analyzed were potentially vulnerable to server-side request forgery attacks.

Without scoping: - An agent with broad access can read environment files, SSH keys, or credentials - Prompt injection attacks can cause agents to write to unintended directories - Accidental destructive actions can affect production configurations or system files

How do I configure scoped filesystem access?

MCP Filesystem Server

The MCP filesystem server accepts allowed directories as command arguments. Only specified paths are accessible:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects/repo-a",
        "/Users/username/notes"
      ]
    }
  }
}

Each directory path explicitly grants access. The server operates with your user account permissions, so only grant access to directories you're comfortable with the agent reading or modifying.

Claude Code

Claude Code defaults to the current working directory. Use additionalDirectories to extend access:

{
  "permissions": {
    "defaultMode": "ask",
    "additionalDirectories": [
      "/home/user/shared-libs",
      "/var/log/myapp"
    ]
  }
}

Store user-level settings in ~/.claude/settings.json and project-specific settings in .claude/settings.json within each repo.

Multi-Agent Setups

For different agents with different permissions, create separate MCP server configurations:

{
  "mcpServers": {
    "docs-readonly": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/docs"]
    },
    "project-workspace": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/projects/active"]
    }
  }
}

Cursor AI

Cursor uses OS-native sandboxing with .cursorignore files to make specified files completely inaccessible. On Linux, it enforces restrictions via Landlock and seccomp at the kernel level. Configure policies in sandbox.json for network and filesystem boundaries.

OpenAI Codex

Codex provides sandbox modes via configuration. Set sandbox_mode = "workspace-write" to limit access to your project directory. Use writable_roots to extend allowed directories, and filesystem profiles to deny reads on sensitive paths like local secrets:

[filesystem]
"~/.secrets" = "none"

Docker Sandboxes and MicroVMs

For stronger isolation, run agents in microVMs with separate kernels. Docker Sandboxes (released March 2026) provides this for Claude Code, Codex, Copilot CLI, and others. Only the workspace directory is shared with the host, and credentials are injected by the host proxy—never stored inside the sandbox.

What are common mistakes to avoid?

Granting home directory access — Never use ~ or /Users/username as a root. Scope to specific project folders.
Using a single broad token — Early MCP examples used one token for full toolset access. Implement per-agent or per-tool authorization.
Forgetting default deny — If something isn't explicitly allowed by policy, the agent shouldn't access it. Set defaultMode: "ask" as a safety net.
Mixing read-only and write servers — Separate knowledge-access servers from workflow servers that modify files.
Static permissions for dynamic needs — Consider time-limited access tokens or session-scoped permissions for sensitive operations.