Filesystem MCP server in Windsurf give Cascade the whole disk — or one folder.
Wire mcp-server-filesystem into Windsurf's Cascade agent through mcp_config.json. One JSON entry, one refresh, and Cascade can read, write, and search directories beyond the project it has open.
Windsurf's Cascade agent already edits the project you have open. mcp-server-filesystem — an npm-packaged MCP server from the ByteDance UI-TARS repo (github.com/bytedance/ui-tars-desktop, 36.3k stars) — extends it to arbitrary directories: read, write, and search local files wherever you point it. Useful for cross-repo work, shared asset folders, or letting Cascade drop build artifacts somewhere specific.
Windsurf keeps its MCP configuration in a single global file, ~/.codeium/windsurf/mcp_config.json. You can edit it directly or get there through Windsurf Settings > Cascade > MCP Servers > Add Server.
Edit mcp_config.json
Open ~/.codeium/windsurf/mcp_config.json — note the .codeium directory, a leftover from Windsurf's Codeium origins and a path people routinely get wrong. Add the server under mcpServers. The directory you pass as the final argument is what the server is allowed to touch; the repo README covers any additional flags.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "mcp-server-filesystem", "/Users/you/projects"]
}
}
}Refresh and confirm
Windsurf doesn't watch the config file. After saving, open the MCP Servers panel (Settings > Cascade > MCP Servers) and hit the refresh action, or restart Windsurf entirely. The server should show as connected with its tool count next to it.
Then ask Cascade something that requires the new tools — list the files in the exposed directory, say — and watch it pick the filesystem tools rather than its built-in workspace operations.
Scope it like you mean it
This server runs with your user account's permissions and can write and modify files within the directories you list. Passing your home directory technically works and is almost never what you want. Name the narrowest path that covers the job — a single project root, an output folder — and add more entries later if Cascade genuinely needs them.
Troubleshooting in Windsurf
Server missing from the panel after a refresh? Re-check the file path first — editing ~/.windsurf/mcp_config.json or a project-local file does nothing; the global ~/.codeium/windsurf/ path is the one Windsurf reads. Then validate the JSON: a trailing comma fails the whole file silently.
If the server appears but shows an error state, the launch command is failing. Windsurf is a GUI app and may not inherit your shell's PATH, so npx can be unreachable even though it works in your terminal — replacing "npx" with its absolute path (run which npx to find it) fixes the majority of these. A nonexistent directory argument is the other classic: the server exits on startup and Windsurf reports it as unreachable. After any config change, refresh the MCP panel or restart the app.
The live listing
Before connecting, you can review the server's live-probed tool list on the Loomal marketplace at https://loomal.ai/marketplace/mcp-server-filesystem. If you maintain an MCP server yourself, claiming its Loomal listing publishes your tool list and opens up per-call pricing for agent traffic.
FAQ
How do I install the Filesystem server in Windsurf?
Add an entry under mcpServers in ~/.codeium/windsurf/mcp_config.json with command npx and args ["-y", "mcp-server-filesystem", "<directory>"], then refresh the MCP Servers panel under Settings > Cascade. The tools become available to Cascade immediately after the server connects.
Where is Windsurf's MCP config file?
At ~/.codeium/windsurf/mcp_config.json — the .codeium directory name comes from Windsurf's previous branding. There's no per-project MCP config; entries in this file apply to every Windsurf window.
Why does the server fail to start even though npx works in my terminal?
GUI apps on macOS don't inherit your shell profile's PATH, so Windsurf may not find npx where your terminal does. Use the absolute path to npx in the command field, or install Node in a standard location, then refresh the MCP panel.
Does Cascade ask before writing files through this server?
Cascade surfaces tool calls before running them unless you've auto-approved the tool, so you'll see write operations proposed in the conversation. Keeping the directory argument narrow is still the stronger safety control.
Browse more MCP servers for Windsurf.
Live-probed tool lists on every Loomal listing.