如何为DeerFlow接入MCP服务器：stdio、SSE、HTTP传输与OAuth认证完整指南

• 人工智能
• AI Agent
• AI 应用
• 多智能体
• Agent 编排
• Agent 沙箱
• Agent 记忆
• AI 技能

🎯 面向新手用户的 DeerFlow 2.0 Enhanced（中文增强版）MCP 接入教程：3 步完成配置，支持 stdio / SSE / HTTP 三种传输方式与 OAuth 自动认证，让 AI 智能体自由调用外部工具。

DeerFlow 2.0 Enhanced 是一个基于多智能体协作的 AI 应用框架，通过接入 MCP（Model Context Protocol）服务器，可以为智能体扩展文件系统、数据库、外部 API、浏览器自动化等能力。本文将带你从零开始，用最简单的方式为 DeerFlow 接入 MCP 服务器，并完整讲透三种传输方式与 OAuth 认证配置。

一、为什么需要给 DeerFlow 接入 MCP 服务器？

MCP 服务器本质上是一个"工具提供者"：它对外暴露一组标准化工具（tools），DeerFlow 会在运行时自动发现这些工具并注入到智能体系统中，无需修改任何代码。

接入后你的智能体可以：

核心实现位于 backend/packages/harness/deerflow/mcp/ 目录，官方说明文档见 backend/docs/MCP_SERVER.md。

二、快速上手：3 步完成 MCP 服务器接入

第 1 步：复制示例配置文件

项目根目录已提供现成的示例配置，只需复制一份并改名：

cp extensions_config.example.json extensions_config.json

这个示例文件 extensions_config.example.json 中预置了 3 个常见服务器模板：filesystem（文件系统）、github（GitHub 操作）、postgres（数据库），全部默认关闭。

第 2 步：启用并修改配置

打开extensions_config.json，把要使用的服务器enabled改为true，并按需修改command、args、env字段。例如启用 filesystem：

{ "mcpServers": { "filesystem": { "enabled": true, "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"], "description": "提供允许目录内的文件系统访问" } } }

第 3 步：重启应用加载工具

重启 DeerFlow 后，MCP 服务器暴露的工具会自动注册给智能体，随后可直接在对话中让 Agent 使用这些工具。

💡小贴士：配置变更会被自动检测——DeerFlow 通过监听extensions_config.json的文件修改时间（mtime）来判断缓存是否失效，修改配置后工具会被自动重新加载，很多场景下无需手动重启。热更新逻辑见 backend/packages/harness/deerflow/mcp/cache.py。

三、三种传输方式详解：stdio、SSE、HTTP

DeerFlow 通过type字段识别传输类型，支持stdio、sse、http三种。参数构建逻辑位于 backend/packages/harness/deerflow/mcp/client.py，配置模型定义在 backend/packages/harness/deerflow/config/extensions_config.py。

3.1 stdio：本地命令行启动（默认方式）

DeerFlow 会在本地直接启动一个子进程，通过标准输入/输出与之通信。适合 npx、uvx 等本地工具，必须提供command字段，缺少会报错requires 'command' field。

{ "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" } }

必填字段：command（启动命令）、args（参数列表）；可选字段：env（传给子进程的环境变量）。

3.2 SSE / HTTP：连接远程服务器

当 MCP 服务器部署在远端（或云端服务）时，使用url字段指向服务端点，必须提供url，缺少会报错requires 'url' field：

{ "type": "http", "url": "https://api.example.com/mcp", "headers": { "X-Api-Key": "你的密钥" } }

• sse：Server-Sent Events 单向推送，适合需要流式事件的场景
• http：标准 HTTP 传输（Streamable HTTP），是目前远程 MCP 的主流选择
• headers：可携带任意自定义请求头，例如静态Authorization令牌

3.3 三种传输方式对比

⚠️ 填写了不识别的type（如websocket）会抛出unsupported transport type错误，请只用以上三种。

四、OAuth 认证：让远程 MCP 服务器更安全

连接需要鉴权的http/sse服务器时，DeerFlow 内置了OAuth 令牌自动获取与自动续期能力：启动时自动拉取令牌，在过期前（默认提前 60 秒）自动刷新，并注入到每次工具调用的Authorization请求头中，全程无需手动维护令牌。完整实现见 backend/packages/harness/deerflow/mcp/oauth.py。

4.1 支持的授权模式

4.2 完整配置示例

{ "mcpServers": { "secure-http-server": { "enabled": true, "type": "http", "url": "https://api.example.com/mcp", "oauth": { "enabled": true, "token_url": "https://auth.example.com/oauth/token", "grant_type": "client_credentials", "client_id": "$MCP_OAUTH_CLIENT_ID", "client_secret": "$MCP_OAUTH_CLIENT_SECRET", "scope": "mcp.read", "refresh_skew_seconds": 60 } } } }

关键字段速查：

• token_url：OAuth 令牌端点地址
• scope/audience：令牌权限范围与受众（按服务商要求填写）
• refresh_skew_seconds：提前多少秒刷新令牌，默认 60
• token_field/expires_in_field：自定义令牌响应字段名，应对非标准 OAuth 服务

五、密钥安全最佳实践：用环境变量代替明文

配置中的$变量名会被自动解析为对应环境变量，因此强烈建议把敏感信息放到环境变量里：

export GITHUB_TOKEN="ghp_xxxxxxxxxxxx" export MCP_OAUTH_CLIENT_ID="your-client-id" export MCP_OAUTH_CLIENT_SECRET="your-client-secret"

解析逻辑位于 backend/packages/harness/deerflow/config/extensions_config.py 中的resolve_env_variables。若环境变量未设置，占位符会被替换为空字符串而不是原文$VAR，避免"假的令牌"被传给服务器。

六、通过 Web 界面或 API 管理 MCP 服务器

除了改文件，DeerFlow 还提供两条"零代码"管理通道：

1. 设置页面：前端 设置 → 工具（Tools）页面可以一键开关每个 MCP 服务器，页面实现见 frontend/src/components/workspace/settings/tool-settings-page.tsx
2. REST API：
   • GET /api/mcp/config：查看当前所有服务器配置
   • PUT /api/mcp/config：整体更新配置并自动落盘

API 路由实现位于 backend/app/gateway/routers/mcp.py，接口文档详见 backend/docs/API.md。

七、常见问题排查

🛠️ 排查技巧：单个服务器配置错误只会被跳过并记录错误日志，不会影响其他正常服务器，可以放心逐个排查。

八、总结

只需一份 JSON 配置，DeerFlow 就能把任意 MCP 服务器暴露的工具无缝接入智能体系统。建议从stdio本地服务器练手，再逐步过渡到带 OAuth 认证的远程http服务器，构建出既强大又安全的 AI 工具生态。

• 人工智能
• AI Agent
• AI 应用
• 多智能体
• Agent 编排
• Agent 沙箱
• Agent 记忆
• AI 技能