diff --git a/backend/docs/API.md b/backend/docs/API.md
index 762a135c4..10ea99858 100644
--- a/backend/docs/API.md
+++ b/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"
}
}
}
diff --git a/backend/docs/MCP_SERVER.md b/backend/docs/MCP_SERVER.md
index b7320f8cc..ba5ccd769 100644
--- a/backend/docs/MCP_SERVER.md
+++ b/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
\ No newline at end of file
+https://modelcontextprotocol.io
diff --git a/extensions_config.example.json b/extensions_config.example.json
index 118c5d6db..7c0dce740 100644
--- a/extensions_config.example.json
+++ b/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": {}
-}
\ No newline at end of file
+}
diff --git a/frontend/src/content/en/harness/mcp.mdx b/frontend/src/content/en/harness/mcp.mdx
index 0e43aa235..53e5ca274 100644
--- a/frontend/src/content/en/harness/mcp.mdx
+++ b/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
}
```
+
+ 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 /mnt/user-data/... to
+ paths accepted by @modelcontextprotocol/server-filesystem.
+
+
Each server entry supports:
- `command`: the executable to run (e.g., `npx`, `uvx`, `python`)
diff --git a/frontend/src/content/zh/application/configuration.mdx b/frontend/src/content/zh/application/configuration.mdx
index 0094323e7..94e78120c 100644
--- a/frontend/src/content/zh/application/configuration.mdx
+++ b/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
}
}
}
```
+
+ 不要为 DeerFlow 工作区文件引入 MCP filesystem server。它会与 DeerFlow
+ 内置文件工具形成路径语义不同的重复能力，让 LLM 行为不稳定。DeerFlow
+ 当前没有为 filesystem server 适配 MCP Roots 模式，也不会把{" "}
+ /mnt/user-data/... 这类沙箱路径映射成{" "}
+ @modelcontextprotocol/server-filesystem 可接受的路径。
+
+
### 技能启用状态
技能启用状态会反映在 `extensions_config.json` 中。你可以直接编辑它，或通过 DeerFlow 应用界面进行管理。
diff --git a/frontend/src/content/zh/harness/mcp.mdx b/frontend/src/content/zh/harness/mcp.mdx
index 4bf72c1a6..0b076aff8 100644
--- a/frontend/src/content/zh/harness/mcp.mdx
+++ b/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
}
```
+
+ 不要为 DeerFlow 工作区文件引入 MCP filesystem server。DeerFlow 已提供按
+ thread 隔离的内置文件工具；重复引入路径语义不同的文件工具，会让 LLM
+ 的工具选择和文件访问行为不稳定。DeerFlow 当前没有为 filesystem server
+ 适配 MCP Roots 模式：不会发布按 thread 收窄的 MCP roots，也不会把{" "}
+ /mnt/user-data/... 这类沙箱路径映射成{" "}
+ @modelcontextprotocol/server-filesystem 可接受的路径。
+
+
每个服务器条目支持：
- `command`：要运行的可执行文件（如 `npx`、`uvx`、`python`）