docs: discourage MCP filesystem workspace config (#3141)

backend/docs/API.md

@@ -241,13 +241,6 @@ GET /api/mcp/config
         "GITHUB_TOKEN": "***"
       },
       "description": "GitHub operations"
-    },
-    "filesystem": {
-      "enabled": false,
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
-      "description": "File system access"
     }
   }
 }

backend/docs/MCP_SERVER.md

@@ -14,6 +14,19 @@ DeerFlow supports configurable MCP servers and skills to extend its capabilities
 3. Configure each server’s command, arguments, and environment variables as needed.
 4. Restart the application to load and register MCP tools.
 
+## Filesystem MCP Servers
+
+DeerFlow already provides built-in file tools for thread-scoped workspace access.
+Do not add an MCP filesystem server for the same DeerFlow workspace. The
+overlapping file tools use different path semantics, which can make LLM tool
+selection and file access behavior unstable.
+
+DeerFlow does not currently adapt the MCP Roots mode for filesystem servers. In
+particular, it does not publish per-thread MCP roots or map DeerFlow sandbox
+paths such as `/mnt/user-data/...` to paths accepted by
+`@modelcontextprotocol/server-filesystem`. Use DeerFlow's built-in file tools
+for DeerFlow workspace files.
+
 ## OAuth Support (HTTP/SSE MCP Servers)
 
 For `http` and `sse` MCP servers, DeerFlow supports OAuth token acquisition and automatic token refresh.
@@ -88,7 +101,6 @@ MCP servers expose tools that are automatically discovered and integrated into D
 
 MCP servers can provide access to:
 
-- **File systems**
 - **Databases** (e.g., PostgreSQL)
 - **External APIs** (e.g., GitHub, Brave Search)
 - **Browser automation** (e.g., Puppeteer)
@@ -97,4 +109,4 @@ MCP servers can provide access to:
 ## Learn More
 
 For detailed documentation about the Model Context Protocol, visit:  
-https://modelcontextprotocol.io
+https://modelcontextprotocol.io

extensions_config.example.json

@@ -3,18 +3,6 @@
     "my_package.mcp.auth:build_auth_interceptor"
   ],
   "mcpServers": {
-    "filesystem": {
-      "enabled": false,
-      "type": "stdio",
-      "command": "npx",
-      "args": [
-        "-y",
-        "@modelcontextprotocol/server-filesystem",
-        "/path/to/allowed/files"
-      ],
-      "env": {},
-      "description": "Provides filesystem access within allowed directories"
-    },
     "github": {
       "enabled": false,
       "type": "stdio",
@@ -42,4 +30,4 @@
     }
   },
   "skills": {}
-}
+}

frontend/src/content/en/harness/mcp.mdx

@@ -29,11 +29,6 @@ The default location is the project root (same directory as `config.yaml`). The
       "args": ["-y", "@my-org/my-mcp-server"],
       "enabled": true
     },
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
-      "enabled": true
-    },
     "sqlite": {
       "command": "uvx",
       "args": ["mcp-server-sqlite", "--db-path", "/path/to/db.sqlite"],
@@ -43,6 +38,16 @@ The default location is the project root (same directory as `config.yaml`). The
 }
 ```
 
+<Callout type="warning">
+  Do not add an MCP filesystem server for DeerFlow workspace files. DeerFlow
+  already provides built-in file tools for thread-scoped workspace access, and
+  overlapping file tools with different path semantics can make LLM tool
+  selection and file access behavior unstable. DeerFlow does not currently
+  adapt MCP Roots mode for filesystem servers: it does not publish per-thread
+  MCP roots or map sandbox paths such as <code>/mnt/user-data/...</code> to
+  paths accepted by <code>@modelcontextprotocol/server-filesystem</code>.
+</Callout>
+
 Each server entry supports:
 
 - `command`: the executable to run (e.g., `npx`, `uvx`, `python`)

frontend/src/content/zh/application/configuration.mdx

@@ -193,15 +193,23 @@ BETTER_AUTH_SECRET=local-dev-secret-at-least-32-chars
 ```json
 {
   "mcpServers": {
-    "filesystem": {
+    "my-server": {
       "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
+      "args": ["-y", "@my-org/my-mcp-server"],
       "enabled": true
     }
   }
 }
 ```
 
+<Callout type="warning">
+  不要为 DeerFlow 工作区文件引入 MCP filesystem server。它会与 DeerFlow
+  内置文件工具形成路径语义不同的重复能力，让 LLM 行为不稳定。DeerFlow
+  当前没有为 filesystem server 适配 MCP Roots 模式，也不会把{" "}
+  <code>/mnt/user-data/...</code> 这类沙箱路径映射成{" "}
+  <code>@modelcontextprotocol/server-filesystem</code> 可接受的路径。
+</Callout>
+
 ### 技能启用状态
 
 技能启用状态会反映在 `extensions_config.json` 中。你可以直接编辑它，或通过 DeerFlow 应用界面进行管理。

frontend/src/content/zh/harness/mcp.mdx

@@ -28,11 +28,6 @@ MCP 服务器在 `extensions_config.json` 中配置，这个文件独立于 `con
       "args": ["-y", "@my-org/my-mcp-server"],
       "enabled": true
     },
-    "filesystem": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
-      "enabled": true
-    },
     "sqlite": {
       "command": "uvx",
       "args": ["mcp-server-sqlite", "--db-path", "/path/to/db.sqlite"],
@@ -42,6 +37,15 @@ MCP 服务器在 `extensions_config.json` 中配置，这个文件独立于 `con
 }
 ```
 
+<Callout type="warning">
+  不要为 DeerFlow 工作区文件引入 MCP filesystem server。DeerFlow 已提供按
+  thread 隔离的内置文件工具；重复引入路径语义不同的文件工具，会让 LLM
+  的工具选择和文件访问行为不稳定。DeerFlow 当前没有为 filesystem server
+  适配 MCP Roots 模式：不会发布按 thread 收窄的 MCP roots，也不会把{" "}
+  <code>/mnt/user-data/...</code> 这类沙箱路径映射成{" "}
+  <code>@modelcontextprotocol/server-filesystem</code> 可接受的路径。
+</Callout>
+
 每个服务器条目支持：
 
 - `command`：要运行的可执行文件（如 `npx`、`uvx`、`python`）