How to Configure the Filesystem MCP Server for AI Agents

Pointing an autonomous agent at a local filesystem with write permissions is the security equivalent of letting a remote contractor run terminal commands without looking. While the Model Context Protocol filesystem server lets models read and write project files, it introduces a massive attack surface if the agent runs malicious code or overwrites system files. Understanding how to configure the server and restrict its scope is essential for any developer using local AI assistants.

The official filesystem MCP server (modelcontextprotocol/server-filesystem) exposes local directory access to AI agents via read/write file tools. The package is hosted under the official modelcontextprotocol GitHub organization as part of the modelcontextprotocol/servers repository. It implements a standard communication channel based on the Model Context Protocol (MCP) specification, enabling LLM clients to discover and run file-based operations.

When an AI agent connects to this server, it receives a capabilities list defining the available file operations. The server exposes the following tools:

• read_text_file: Reads the complete contents of a text file. It accepts a path parameter and supports optional head and tail parameters to read specific line ranges.
• read_multiple_files: Reads the contents of multiple files at once.
• write_file: Creates a new file or completely overwrites an existing file with the provided text content.
• edit_file: Applies precise changes to a text file by searching for a specific target string and replacing it with new content.
• create_directory: Creates a new directory path. It operates recursively and succeeds if the directory already exists.
• list_directory: Lists the files and subdirectories directly inside a specified folder.
• directory_tree: Generates a recursive JSON tree view of the directory contents, showing files, folders, and nested children.
• move_file: Relocates or renames a file or directory from a source path to a destination path.
• search_files: Recursively searches for files and directories that match a glob pattern.
• get_file_info: Retrieves file metadata, including size, creation time, and last modified date.
• list_allowed_directories: Lists the absolute paths currently authorized for server access.

Note that the legacy read_file tool is deprecated in the official repository. Developers are encouraged to use read_text_file instead, as it handles text encodings better and supports partial reads. Partial reads prevent large files from filling the model's context window, saving token costs and reducing latency.

• How to Track C++ File Modifications with std::filesystem::last_write_timeTracking file modification times is essential for C++ applications synchronizing local files with shared workspaces....
• ChatGPT SharePoint Connector: Enterprise Setup vs. Fast.io MCP WorkspacesConnecting ChatGPT to SharePoint document libraries gives conversational models access to enterprise knowledge. While...
• Resolving Secure Sandbox Paths with std::filesystem::canonicalThe std::filesystem::canonical function resolves all symbolic links, relative segments, and redundant separators in C++...
• How to Secure C++ Agent Sandboxes With std::filesystem::permissionsDynamic file creation by autonomous coding agents introduces the risk of file corruption and privilege escalation....
• Connecting AutoGen Multi-Agent Systems to SharePoint: Architecture and SetupAn AutoGen SharePoint connector enables Microsoft AutoGen agent teams to authenticate against Microsoft Graph and query...
• Amazon Bedrock SharePoint Connector: Setup, Limitations, and AlternativesThe Amazon Bedrock SharePoint connector allows Amazon Bedrock Knowledge Bases to ingest and index documents stored in...

More on this subject: Agent File and Document Workflows (298 guides)

To connect Claude Desktop to the filesystem MCP server, you must edit its configuration file. This file is named claude_desktop_config.json and is located in the application support folder of your operating system.

Depending on your environment, you can locate the configuration file at the following absolute paths:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

If the file does not exist in these directories, you must create a new text file named claude_desktop_config.json and initialize it. Add the filesystem server configuration under the mcpServers block:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/workspace/project-a",
        "/Users/username/workspace/project-b"
      ]
    }
  }
}

Let's examine how this configuration works:

• mcpServers: This is the top-level configuration key that Claude Desktop reads to launch MCP servers at startup.
• filesystem: The unique identifier for this server instance.
• command: The executable command used to run the server. We use npx to execute the Node.js package. This requires Node.js v18 or higher to be installed on your local machine and available in your system path.
• args: The arguments passed to the command. The -y flag forces npx to download and install the @modelcontextprotocol/server-filesystem package without prompting you for confirmation. The subsequent strings in the array are the absolute paths to the directories you authorize.

Some developers use other coding assistants like the Cline extension in Visual Studio Code. While Cline uses a similar configuration structure, its settings are stored in a file named cline_mcp_settings.json located in its own extension directory. Always ensure you edit the specific settings file for your target client. After editing the configuration file, you must restart Claude Desktop or reload your client application to apply the changes and launch the server.

The filesystem MCP server requires explicit directory permissions. By default, the server denies access to all paths on your machine. You must define each authorized folder as an absolute path in the server's arguments list. If you do not pass any directory paths during startup, the server initializes with an empty allowed list and rejects all file tools.

When the AI client invokes a tool like read_text_file or write_file, the server performs path validation. This security mechanism operates through the following steps:

1. The server receives a target file path from the AI agent.
2. It resolves the path to its canonical form using the operating system's realpath function. This step resolves all relative segments, symbolic links, and shorthand references.
3. It checks if the resolved canonical path is a child of at least one of the configured allowed directories.
4. If the path is within the boundary, the server executes the filesystem operation. If the path falls outside the boundary, the server blocks the operation and returns an access denied error.

This validation mechanism prevents directory traversal attacks. For example, if you allow access only to /Users/username/project, the agent cannot read files in other system folders. If the agent attempts to pass a path like /Users/username/project/../../.ssh/id_rsa, the path validator resolves the relative segments to /Users/username/.ssh/id_rsa and blocks the request.

However, developers must understand how permissions operate. The server process runs as a local child process under your user account. It inherits all of your system permissions. It cannot read files that you do not have permission to read, but it has access to any files you can modify. If you run the client with administrator privileges, or if you include sensitive key folders in the allowed list, the agent can read and modify those critical files.

Secure your modelcontextprotocol/server-filesystem data in the cloud

Stop running local node servers. Connect your AI agents to Fastio workspaces with per-file version history, granular access controls, and remote MCP endpoints. Start your 14-day free trial today, credit card required.

Start 14-Day Trial

Most guides ignore the security risk of giving an agent full write access to your local workspace, and don't provide a cloud-based sandbox alternative. While restricting directories prevents the agent from reading system configuration files, it does not secure the files within the allowed directories themselves. Once you give an agent access to a project folder, you expose your active code to several security and operational risks.

Consider the primary risks associated with local write access:

• Accidental Deletion of Source Code: AI agents are autonomous and can make errors. If you ask an agent to clean up deprecated modules, a logic error or directory traversal hallucination can cause it to delete active development directories.
• Prompt Injection Vulnerabilities: If the agent reads an external document or source file that contains hidden instructions, it can execute those commands. For example, a file might contain a malicious instruction telling the agent to overwrite your main entry point with empty data.
• Secret and Credential Exposure: Many developers store API keys, database credentials, and private environment variables in .env files inside their project root. If the agent has read access to the project directory, it can read these credentials and print them in logs or send them to external API endpoints.
• Infinite Loop Writes: If an agent enters an infinite loop, it can write repetitive data to a log file or create endless subdirectories, consuming local disk space and causing system instability.

These risks highlight the need for isolation. Running agents directly on your development machine with raw write permissions on your active code creates a high probability of file loss or security exposure.

To protect your local environment from the security risks of direct filesystem access, you can use Fastio as a secure, cloud-based workspace. Instead of running local servers and allowing agents to edit files on your hard drive, you can import your project files into a Fastio workspace. Fastio serves as an intelligent workspace where humans and agents collaborate safely.

Using Fastio provides several security and coordination features:

• Per-File Version History: Fastio automatically maintains a full history of every file in the Fastio workspaces. If an agent writes faulty code, overwrites a configuration file, or deletes an asset, you can view the changes and restore a previous version from the web interface.
• Granular Access Controls: You can configure permissions at the organization, workspace, folder, or file level. This allows you to restrict the agent's write access to specific output directories while protecting your main design documents.
• Append-Only Audit Log: Every file creation, modification, deletion, and import is recorded in an immutable audit log. This log gives you full visibility into exactly what files the agent modified and when.
• Coordination Rooms: Fastio supports Fastio Coordination Rooms, which are shared workspaces carrying a server-owned room flag where humans and agents post messages and files, allowing multiple agents to hand off work without sync conflicts.
• Workspace Intelligence Mode: Fastio automatically indexes your workspace documents for semantic search. Agents can use this search layer to find context across thousands of files without downloading the files locally.
• Remote MCP Server: Connect your agent directly to Fastio remote MCP server or the key-based endpoint at /storage-for-agents/ with an API token in the Authorization: Bearer header. The agent executes file tools in the cloud workspace, ensuring your local machine remains isolated.

Getting started is straightforward. Creating a user account is free; doing real work requires an organization on a paid subscription. Every organization starts with a 14-day free trial, which requires a credit card. Fastio plans are Starter at $9.99/mo, Business at $49.99/mo, and Enterprise at $199.99/mo. Once your organization is set up, you can import files from external storage services or URLs, enable workspace intelligence, and point your agent to Fastio remote MCP server. This setup allows you to use agentic workflows without risking your local system files. For detailed subscription terms, check the Fastio pricing page.