Setting Up the MCP Filesystem Server on Mac: Local Permissions and Remote Agent Storage

Architecture of Stdio Transport in macOS Environments

The stdio transport model relies on clean, uninterrupted communication streams between the host application and the spawned process. When Claude Desktop or Cursor initiates @modelcontextprotocol/server-filesystem, the operating system creates an anonymous unidirectional pipe for input and another for output.

Because standard output carries machine-readable JSON-RPC frames, any extraneous text written to stdout corrupts the communication protocol. If a shell profile script, a global npm hook, or an unhandled warning prints text to standard output during startup, the host application fails to complete the initial protocol handshake. To maintain protocol reliability, all runtime logging and diagnostic outputs must be directed to standard error (stderr).

Child processes also share the execution lifecycle of their host. If Claude Desktop crashes, closes during an automated restart, or terminates during an operating system sleep cycle, the child Node.js process shuts down immediately. Any uncommitted file operations or in-flight agent edits risk leaving partial writes on the local disk.

Path Sandboxing and the MCP Roots Protocol

To prevent prompt injection attacks or runaway agent loops from reading arbitrary system files, @modelcontextprotocol/server-filesystem enforces path containment. When configuring the server, developers pass absolute paths that serve as an allowed boundary list:

/Users/username/Projects/app    <-- Declared root
├── src/index.ts                <-- Permitted read and write
└── ../../.ssh/id_rsa           <-- Rejected (Path traversal outside root)

Before executing any read or write, the server resolves symbolic links using fs.realpathSync to ensure the canonical target path remains strictly within an allowed root directory. If an agent attempts relative path traversal using ../ patterns, the server returns an access denied error.

Modern MCP clients also support the MCP roots protocol (roots/list), which allows the client application to dynamically negotiate boundary adjustments as project folders open and close, without requiring the developer to manually restart the underlying process.

Setting Up claude_desktop_config.json in macOS Application Support

On macOS, Claude Desktop stores its user configuration inside the Application Support folder. The exact configuration file path is:

~/Library/Application Support/Claude/claude_desktop_config.json

You can open this file directly from Claude Desktop by opening Settings, selecting the Developer tab, and clicking Edit Config. Alternatively, you can open it in your preferred text editor using Terminal:

open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

Inside claude_desktop_config.json, add the filesystem entry under the top-level mcpServers object. Crucially, macOS does not expand the tilde (~) character when evaluating JSON configuration arguments inside spawned child processes. You must write out the complete absolute path starting with /Users/<your-username>:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Projects",
        "/Users/username/Documents/Specs"
      ]
    }
  }
}

Replace /Users/username/Projects with the actual directories you wish to expose. After saving the file, completely quit Claude Desktop by pressing Command+Q and relaunch the application.

To confirm the connection, open a new chat in Claude Desktop and look for the hammer icon in the bottom right corner of the prompt box. Clicking the icon displays the active tool list, which includes:

• read_file: Reads the complete text content of a local file.
• read_multiple_files: Reads several files simultaneously.
• write_file: Creates a new file or completely replaces an existing file.
• edit_file: Applies targeted string substitutions within an existing file.
• create_directory: Recursively creates new directory paths.
• list_directory: Lists file names and directory contents.
• directory_tree: Generates a recursive hierarchical directory map.
• move_file: Renames or relocates files between permitted directories.
• search_files: Searches for files matching glob patterns.
• get_file_info: Retrieves file metadata including size, creation time, and modification date.
• list_allowed_directories: Displays the active root paths permitted for the session.

Configuring Cursor with Project-Level and Global MCP Settings

Cursor supports MCP servers through both global user settings and repository-level configurations. This flexibility allows engineering teams to check standard tool definitions directly into version control while keeping personal workstations flexible.

To configure the filesystem server globally for your macOS user account, create or edit the global MCP configuration file:

~/.cursor/mcp.json

Add the filesystem server definition using the mcpServers object:

{
  "mcpServers": {
    "local-fs": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Development"
      ]
    }
  }
}

For repository-specific scoping, create a .cursor/mcp.json file inside the root of your project directory. This limits the agent to the current workspace, preventing unintentional reads across unrelated repositories on your computer.

After saving the configuration, open Cursor Settings, navigate to Features, and select MCP to verify that the server status indicates a green active state. Once verified, Cursor's composer and chat agents can read files, write unit tests, and inspect directory trees directly through the toolset.

Resolving macOS Transparency, Consent, and Control (TCC) Permission Denies

Modern versions of macOS enforce strict privacy boundaries around user data folders, including ~/Desktop, ~/Documents, and ~/Downloads. These boundaries are managed by Apple's TCC subsystem.

When Claude Desktop or Cursor launches npx to run the MCP server, Node.js runs as a child process. macOS attributes filesystem system calls back to the parent application binary. If the parent application lacks explicit authorization to access protected user directories, the operating system kernel immediately blocks the request.

In the agent session, this failure manifests as an unexpected runtime crash or an explicit POSIX error:

Error: EPERM: operation not permitted, scandir '/Users/username/Documents'

To resolve this issue, you must grant Full Disk Access to the host application:

1. Open System Settings on your Mac.
2. Navigate to Privacy & Security in the sidebar.
3. Scroll down and click Full Disk Access.
4. Locate Claude or Cursor in the application list and toggle the switch to On.
5. If the application is not listed, click the plus (+) button at the bottom of the list, authenticate with your macOS password or Touch ID, navigate to /Applications, and select the app.
6. If you execute agents through command-line scripts or custom Python wrappers, ensure that Terminal, iTerm2, or your specific Node binary has Full Disk Access enabled.
7. Quit and relaunch the host application so the new security entitlements take effect.

Granting Full Disk Access resolves EPERM and EACCES errors, allowing the child process to read and write across all directories declared in its configuration arguments.

The 0-Byte Dataless Cloud Storage Problem in macOS FileProvider

Many teams store project files, design assets, and research documents in cloud platforms like Dropbox, Google Drive, OneDrive, Box, or SharePoint. On macOS, modern versions of these services do not run as legacy kernel extensions. Instead, they rely on Apple's native FileProvider framework, mounting synchronized folders inside:

~/Library/CloudStorage/

For example, a business OneDrive account mounts at ~/Library/CloudStorage/OneDrive-Company, while Dropbox mounts at ~/Library/CloudStorage/Dropbox.

To conserve physical SSD space, cloud storage providers default to on-demand file streaming. In Finder, these files appear with a small cloud icon indicating they are online-only. Apple terms these items "dataless files." A dataless file contains complete filesystem metadata (filename, byte size, creation timestamp, and extended attributes), but zero bytes of physical content stored on the local disk.

When a human double-clicks a dataless file in Finder, macOS intercepts the action and sends an upcall to the system daemon (fileproviderd). The daemon downloads the file content from the cloud, writes the blocks to disk, and transitions the file from dataless to materialized.

However, when an AI agent runs @modelcontextprotocol/server-filesystem via Node.js, the server executes standard POSIX file read operations:

// Standard POSIX read executed by local MCP filesystem server
const data = fs.readFileSync('/Users/username/Library/CloudStorage/OneDrive-Company/report.pdf');

POSIX read calls do not invoke Apple's high-level NSFileCoordinator or trigger the necessary FileProvider materialization upcalls. Because the physical disk blocks contain no data, the system call behaves in one of three problematic ways:

1. Empty byte buffers: The read operation returns immediately with zero bytes. The AI agent assumes the file is empty and informs the user that the document contains no text.
2. Process hangs and timeouts: The call blocks waiting for a system response that never completes, causing the MCP server to time out and drop the connection.
3. Resource deadlock errors: The operating system returns an explicit POSIX failure, EDEADLK (Resource deadlock avoided).

If an agent attempts to write updates back to an unhydrated dataless placeholder, it can overwrite the cloud stub with a truncated local file, damaging remote cloud document integrity.

While developers can manually right-click folders in Finder and select "Always Keep on This Device" to force local download, this manual workaround quickly breaks down. Autonomous agents frequently navigate dynamic subdirectories and handle newly created assets where manual pre-downloading is impractical.

Process Isolation, Context Window Bloat, and Team Barriers

Operating AI agents through local stdio filesystem servers presents three critical bottlenecks:

• Single-workstation confinement: Artifacts created by Claude Desktop or Cursor remain trapped on the local developer laptop. A research document or code patch generated by an agent cannot be inspected by teammates, reviewed by managers, or accessed by automated background systems without manual export.
• Context window exhaustion: The local filesystem server provides raw read primitives. When an agent needs to answer questions about project documents, it must read entire files into the active LLM context window. Reading several large PDFs or codebases consumes tens of thousands of tokens, increasing inference latency and compute costs.
• Multi-agent file collisions: When multiple agents operate concurrently on the same local directory over stdio, they have no shared locking mechanism. If one agent rewrites a file while another is generating edits based on an earlier version, the second agent overwrites the first without warning.

In addition, modern work patterns require access across environments. When using Claude on mobile devices, working from secondary laptops, or deploying autonomous agents to cloud servers, local paths like /Users/username/Projects are inaccessible.

Grounded RAG, Scheduled Cloud Sync, and Persistent Workspaces

Remote agent workspaces solve these limitations by decoupling storage and indexing from the local developer machine. Instead of reading raw local disk blocks over stdio pipes, agents connect to hosted workspaces through remote MCP endpoints.

In an intelligent workspace platform like Fastio, files are automatically indexed on arrival. When an agent needs specific facts, it queries the workspace through hybrid search, combining full-text keyword matching and semantic vector retrieval. The agent receives concise, relevant document excerpts with citations rather than ingesting entire multi-megabyte files into its prompt context.

For teams that already store business files in cloud storage platforms, Fastio provides scheduled Cloud Sync for Google Drive, Dropbox, Box, and OneDrive (one-way or two-way, on a schedule or on demand, never continuous, live, or real-time; SharePoint libraries connect through the OneDrive connector). This architecture allows teams to maintain their existing cloud storage structure while the synchronized Fastio workspace serves as the intelligent, indexed layer for AI agents.

The connector comparison is published at fast.io/benchmarks/ and that page is the only place its numbers live. In that published testing, Fastio was measured the fastest and the lowest cost of the providers tested. Every measured row evaluated that provider's native connector in Claude Cowork; no row evaluated a local stdio server, a Files-On-Demand stub, or SharePoint, and SharePoint was not measured at all.

Fastio organizes shared workspaces with clear plan boundaries designed for organizations and teams:

Monthly plans start with a 14-day free trial that requires a credit card and ends early if its trial credits run out. Credits meter AI work only, with overage at $10 per 100,000 credits. Storage beyond the plan is $0.015 per GB a month and extra bandwidth is $0.04 per GB.

Setting Up the Fastio Custom Connector in Claude Apps

Claude applications (including Claude web, Claude Desktop, and Claude mobile) connect to Fastio using Claude's native connector interface:

1. In Claude, open Customize, then select Connectors.
2. Click Add Custom Connector.
3. In the Connector URL field, enter the official Streamable HTTP endpoint: https://mcp.fast.io/mcp/tools.
4. Select Connect. A browser window opens prompting you to sign in to Fastio.
5. Review the permissions screen, choose Read Only or Read & Write access, and select which organizations and workspaces the connection can access.
6. In any active Claude conversation, enable Fastio from the plus (+) menu under Connectors.

Never edit claude_desktop_config.json to configure Fastio. Claude's custom connector interface manages authentication and session tokens securely through browser OAuth, ensuring your agent connection works cleanly across desktop, web, and mobile environments. Setup instructions and full documentation are available at mcp.fast.io/docs.

Connecting Cursor and Coding Agents via Streamable HTTP Endpoints

Coding agents operating in developer IDEs and terminal environments connect to Fastio using the dedicated /mcp/code endpoint. This endpoint exposes a consolidated MCP toolset optimized for code development, including search, execute, execute_manage, upload, upload_manage, and how-to.

To connect Cursor to your Fastio workspace, open your global configuration at ~/.cursor/mcp.json (or .cursor/mcp.json in your project root) and add the remote server:

{
  "mcpServers": {
    "fast-io": {
      "url": "https://mcp.fast.io/mcp/code"
    }
  }
}

For developers using Claude Code in the terminal, add the connection with a single command:

claude mcp add --transport http fast-io https://mcp.fast.io/mcp/code

After adding the server, complete OAuth sign-in in the browser to finish authenticating.

Once connected, coding agents can query workspace knowledge bases, verify technical specifications, and write code artifacts directly into shared project folders. Because every file retains per-file version history, developers can inspect every agent modification, restore prior file states, and collaborate with human teammates through shared workspaces.

When an agent completes a client deliverable, teams can use ownership transfer to hand off the organization from an agent account to a human with a claim link, while retaining administrative oversight.