MCP (Model Context Protocol) 系统实现说明

May 15, 2026

概述

DeerFlow完整集成了MCP（Model Context Protocol）协议，支持无缝对接各类MCP服务器，实现工具能力的动态扩展。系统采用模块化设计，支持多种传输协议、OAuth 2.0认证、运行时热更新、自动缓存等企业级特性，无需修改代码即可通过配置扩展Agent的工具能力。

核心架构

1. 文件结构

所有MCP相关代码集中在packages/harness/deerflow/mcp/目录下：

文件	职责
`mcp/__init__.py`	模块导出接口，统一暴露核心函数
`mcp/cache.py`	MCP工具缓存机制，支持自动失效与懒加载
`mcp/client.py`	MCP客户端实现，支持多传输类型配置构建
`mcp/oauth.py`	OAuth令牌管理，支持自动刷新与请求头注入
`mcp/tools.py`	工具加载与同步适配，将MCP工具转换为LangChain兼容格式
`config/extensions_config.py`	配置解析系统，定义MCP配置结构与加载逻辑
`app/gateway/routers/mcp.py`	Gateway API层，提供MCP配置的REST管理接口

2. 整体架构

┌─────────────────────────────────────────────────────────┐
│                     Agent Runtime                        │
└─────────────────┬─────────────────────────────────────────┘
                  │
┌─────────────────▼─────────────────────────────────────────┐
│                   MCP Tool Cache                          │
│  (懒加载、自动失效、线程安全)                              │
└─────────────────┬─────────────────────────────────────────┘
                  │
┌─────────────────▼─────────────────────────────────────────┐
│              MultiServerMCPClient                         │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐          │
│  │ Stdio 服务 │  │ SSE 服务   │  │ HTTP 服务  │          │
│  └────────────┘  └────────────┘  └────────────┘          │
└─────────────────┬─────────────────────────────────────────┘
                  │
┌─────────────────▼─────────────────────────────────────────┐
│                  OAuth 管理器                             │
│  (令牌自动刷新、线程安全、请求头自动注入)                  │
└─────────────────┬─────────────────────────────────────────┘
                  │
┌─────────────────▼─────────────────────────────────────────┐
│                MCP 服务器集群                              │
│  (本地进程、远程服务、第三方MCP服务)                       │
└───────────────────────────────────────────────────────────┘

配置系统

1. 配置格式

MCP服务器配置存储在extensions_config.json文件中，示例：

{
  "mcpServers": {
    "github": {
      "enabled": true,
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@github/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      },
      "description": "GitHub API 工具集"
    },
    "internal-api": {
      "enabled": true,
      "type": "http",
      "url": "https://mcp.example.com/tools",
      "oauth": {
        "enabled": true,
        "token_url": "https://auth.example.com/oauth2/token",
        "grant_type": "client_credentials",
        "client_id": "$CLIENT_ID",
        "client_secret": "$CLIENT_SECRET",
        "scope": "read write"
      },
      "description": "内部系统API工具集"
    }
  }
}

2. 传输类型

支持三种传输协议：

类型	适用场景	配置参数
`stdio`	本地MCP服务器，通过子进程启动	`command`、`args`、`env`
`sse`	远程SSE协议的MCP服务器	`url`、`headers`
`http`	远程HTTP协议的MCP服务器	`url`、`headers`

3. 路径解析优先级

显式传入的config_path参数
DEER_FLOW_EXTENSIONS_CONFIG_PATH环境变量
当前工作目录下的extensions_config.json
当前工作目录父目录下的extensions_config.json（推荐位置）
兼容旧版：查找mcp_config.json作为备选

4. 环境变量注入

配置中所有以$开头的字符串会自动解析为环境变量
示例："GITHUB_TOKEN": "$GITHUB_TOKEN"会自动替换为对应环境变量的值
未找到的环境变量自动替换为空字符串，避免运行错误

核心功能实现

1. OAuth 2.0 认证系统

支持完整的OAuth 2.0客户端认证能力：

支持的授权模式

client_credentials：客户端凭证模式，适用于服务间通信
refresh_token：刷新令牌模式，适用于用户级授权场景

核心特性

自动刷新：提前60秒（可配置refresh_skew_seconds）自动刷新令牌，避免请求时令牌过期
线程安全：每个MCP服务器独立的令牌获取锁，避免并发刷新导致的重复请求
自动注入：工具调用拦截器自动将最新的Authorization头注入到所有MCP请求中
初始化认证：首次连接MCP服务器时自动注入OAuth头，确保工具发现阶段的认证通过

2. 工具加载与适配

自动发现：自动加载所有启用MCP服务器暴露的工具，无需手动定义
名称隔离：工具名称自动添加服务器前缀，避免不同服务器之间的命名冲突，格式为{server_name}_{tool_name}
同步适配：异步MCP工具自动封装为同步调用，适配DeerFlow的同步执行模型，使用全局线程池避免嵌套事件循环问题
类型转换：自动处理MCP工具参数与LangChain工具格式的转换，上层调用无感知

3. 缓存机制

缓存策略

全局单例缓存：MCP工具加载后全局缓存，避免重复初始化的性能开销
自动失效：通过监控配置文件的修改时间（mtime），配置变更后自动失效缓存，下次访问时重新加载
懒加载：支持首次使用时自动初始化，兼顾冷启动性能和资源占用
线程安全：初始化过程使用异步锁，避免并发场景下的重复初始化问题

管理接口

# 获取MCP工具（自动初始化、自动缓存）
from deerflow.mcp import get_cached_mcp_tools
tools = get_cached_mcp_tools()

# 手动重置缓存（配置更新后调用）
from deerflow.mcp import reset_mcp_tools_cache
reset_mcp_tools_cache()

4. 运行时热更新

配置文件修改后，系统自动检测到mtime变化，缓存自动失效
通过Gateway API更新配置后，自动触发缓存重置
新配置在下次工具调用时自动生效，无需重启LangGraph或Gateway服务
更新过程中不影响现有会话的运行

工作流程

完整执行流程

初始化触发：应用启动或首次调用MCP工具时，get_cached_mcp_tools()被调用
配置加载：从extensions_config.json加载所有启用的MCP服务器配置，解析环境变量
OAuth初始化：为需要认证的服务器初始化OAuth令牌管理器，获取初始访问令牌
客户端创建：构建MultiServerMCPClient实例，连接所有MCP服务器
工具发现：自动从所有MCP服务器发现并加载工具定义
工具适配：将异步MCP工具封装为同步调用，添加服务器前缀，存入全局缓存
工具使用：Agent调用MCP工具时，OAuth拦截器自动注入最新令牌，同步包装器处理异步调用逻辑
缓存失效：当配置文件被修改时，缓存自动失效，下次访问时重新执行初始化流程

API管理接口

Gateway提供了REST接口用于管理MCP配置：

获取当前配置

GET /api/mcp/config

返回所有MCP服务器和技能的配置信息。

更新配置

PUT /api/mcp/config
Content-Type: application/json

请求体为新的MCP配置，保存到文件后自动重置缓存，新配置立即生效。

注意：更新MCP配置时不会覆盖已有的技能配置，实现MCP与技能配置的独立管理。

关键特性

零代码扩展：新增MCP服务器只需修改配置文件，无需修改业务代码
运行时热更新：配置修改后自动生效，无需重启服务
多场景适配：支持本地命令行、远程SSE/HTTP等多种MCP服务器部署方式
企业级安全：完整的OAuth 2.0支持，满足内部API和第三方API的安全访问需求
高性能设计：缓存机制与自动失效平衡了性能和配置实时性
兼容现有架构：同步包装器完美适配DeerFlow现有的同步执行模型，无需修改上层调用逻辑

最佳实践

敏感信息管理：所有API密钥、令牌都通过环境变量传递，不要硬编码在配置文件中
命名规范：MCP服务器名称使用小写字母和连字符，避免特殊字符
权限最小化：为MCP服务器配置最小必要的权限，避免过度授权
版本锁定：本地stdio类型的MCP服务器推荐锁定版本号，避免意外升级导致兼容性问题
监控告警：对重要的MCP服务器添加健康检查，及时发现服务不可用问题