MCP Spotlight: Filesystem MCP — The Reference Implementation That Every Coding Agent Ships

Server: @modelcontextprotocol/server-filesystem by Model Context Protocol Stars: 261K (MCP repo) · Downloads: 86,964+ (this server) · Tools: 14 · License: MIT MCP Tracker: glama.ai/mcp/servers/modelcontextprotocol/filesystem Docs: github.com/modelcontextprotocol/servers

If you've ever given an AI agent access to your local files, you've used this server. The official Filesystem MCP server from the Model Context Protocol team is the reference implementation every coding agent integrates with — 86,964+ downloads, 14 tools, and the template that other filesystem servers follow.

It's also the canonical example of three things that every filesystem-adjacent MCP server should get right: directory access control, tool annotations, and the Roots protocol.

The 14 Tools

Tool	Read/Write	Idempotent	Destructive	What It Does
read_text_file	Read	—	—	Read file contents as UTF-8 text; supports head / tail for partial reads
read_media_file	Read	—	—	Read an image or audio file as base64 with the MIME type
read_multiple_files	Read	—	—	Read several files in one call; failed reads don't stop the operation
write_file	Write	✓	✓	Create or overwrite a file
edit_file	Write	—	✓	Selective pattern-matched edits with diff preview (dryRun)
create_directory	Write	✓	—	Create a directory (and parents) or no-op if it exists
list_directory	Read	—	—	List directory contents with [FILE] / [DIR] prefixes
list_directory_with_sizes	Read	—	—	Same as above plus sizes and summary statistics
move_file	Write	—	✓	Move or rename files and directories
search_files	Read	—	—	Recursive glob-style search with optional excludes
directory_tree	Read	—	—	Recursive JSON tree of directory contents
get_file_info	Read	—	—	File/directory metadata: size, times, type, permissions
list_allowed_directories	Read	—	—	Shows which directories the server is sandboxed to
(sandbox)	—	—	—	Enforces the directory allowlist on every operation

The first thing to notice: read tools are clearly distinguished from write tools in the schema annotations. This is the reference pattern for safety — clients can render read operations as informational, write operations as confirmable.

Tool Annotations: The Pattern Worth Copying

The Filesystem MCP server is one of the first to ship with full MCP Tool Annotations — three hints that make the protocol expressive enough to build safety UX on top of:

Annotation	What It Tells the Client
readOnlyHint: true	The tool cannot modify any state. Safe to call freely.
idempotentHint: true	Calling the tool with the same args has the same effect as calling it once. Safe to retry.
destructiveHint: true	The tool can cause significant data loss or overwrite. Surface a confirmation.

The reference pattern:

read_text_file         readOnlyHint=true,  no idempotent/destructive hints
write_file             readOnlyHint=false, idempotentHint=true,  destructiveHint=true
edit_file              readOnlyHint=false, idempotentHint=false, destructiveHint=true
move_file              readOnlyHint=false, idempotentHint=false, destructiveHint=true
create_directory       readOnlyHint=false, idempotentHint=true,  destructiveHint=false

A well-built MCP client uses these hints to:

• Render read tools as "View" actions, write tools as "Edit" actions
• Auto-retry idempotent writes on network failure
• Show a HITL confirmation prompt for destructiveHint: true tools before the call
• Skip confirmation for idempotentHint: true writes

This is how MCP servers signal safety intent to clients, and the Filesystem server is the reference implementation. If you're building a write-capable MCP server, the Filesystem server's annotation table is the template to copy.

Directory Access Control: The Two Methods

The single most important safety property: the server is sandboxed to a set of allowed directories, and every operation is restricted to those directories.

There are two ways to configure the allowlist:

Method 1 — Command-line arguments (legacy, simple)

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

The server starts with these directories hard-coded. Every read_text_file, write_file, and move_file call checks that the resolved path is within one of the allowlisted directories. If you try to read /etc/passwd, the call is rejected.

Method 2 — MCP Roots (recommended, modern)

MCP clients that support the Roots protocol send the allowlist to the server at initialization and can update it at runtime:

1. Server starts with empty allowlist (or command-line fallback)
2. Client connects and sends initialize with capabilities.roots
3. Server requests roots via roots/list
4. Client responds with its current working directories
5. Server replaces the allowlist with the client's roots
6. At runtime, client can send notifications/roots/list_changed → server fetches new roots → allowlist updates without restart

This is the architectural pattern that makes agentic IDEs safe: the user opens a workspace in Cursor, VS Code, or Claude Code; the IDE sends the workspace root via Roots; the filesystem server scopes itself to that workspace. Open a different project, the server automatically rescopes.

The server requires at least one allowed directory — if no command-line args are given and the client doesn't support roots, initialization fails fast.

Facio Integration

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem",
               "${workspace.path}"],
      "env": {}
    }
  }
}

The ${workspace.path} placeholder resolves to the current Facio workspace — a single directory containing the agent's working files. Combined with Facio's audit trail, every file operation is logged with its full path, content diff, and timestamp. For HITL workflows, the combination is powerful:

• The edit_file tool supports dryRun: true — the agent previews the diff and shows it to the human before applying
• The destructiveHint: true annotation signals the client to require confirmation for write_file and move_file
• Facio captures the full before/after content, the timestamp, the agent's reasoning, and the human's approval

For teams shipping production agents, this is the safety stack: directory sandbox (server) + tool annotations (protocol) + dry-run previews (tool feature) + HITL confirmation (client) + audit trail (Facio). Five layers, each independent.

Quickstart

# NPX (simplest)
npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

# Add to your MCP client config
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem",
               "/Users/me/projects"]
    }
  }
}

# Or Docker (mounts to /projects, supports :ro for read-only mounts)
docker run -i --rm \
  --mount type=bind,src=/Users/me/projects,dst=/projects/projects \
  --mount type=bind,src=/Users/me/notes,dst=/projects/notes,ro \
  mcp/filesystem /projects

# First prompts
# "List the contents of /projects"
# "Find all .ts files in src/ that import from 'axios'"
# "Show me the directory tree of src/ — exclude node_modules"
# "Edit src/api/users.ts to add input validation (preview first)"
# "Move all *.log files in /projects/logs to /projects/archive/2026-06/"

Why the Reference Implementation Matters

Most "filesystem MCP server" projects in the wild are forks of this one or reimplementations following its pattern. The combination of:

1. Explicit allowlist sandboxing (the directory access control)
2. MCP Tool Annotations on every tool
3. Roots protocol support for runtime rescoping
4. Multi-platform packaging (NPX, Docker, Windows cmd /c shim)
5. Tool features that support safety UX (edit_file with dryRun)

…is the template. If you're building any write-capable MCP server, this is the bar. Read it, copy the patterns, set the right tool annotations. Your users will thank you.

Bottom Line

The Filesystem MCP server is the reference implementation every other server is measured against. 14 tools, 86,964+ downloads, full Tool Annotations, dynamic directory access control via Roots, and the safety patterns that ship in nearly every coding agent that touches your local files.

If you're building an MCP server, study this one. If you're integrating an agent with the filesystem, use this one. The pattern is the protocol.

---

MCP Spotlight is a series covering servers that give AI agents real capabilities. Every server is evaluated for tool design, safety architecture, and integration fit with Facio's HITL-first agent runtime.