agentic_huge_data_base / wiki
页面 Dify · 7.3 MCP 协议集成·DeepWiki 中文全文译文
DeepWiki 中文译文 / Dify / 7.3

7.3 · MCP 协议集成（MCP Protocol Integration）

应用编排与外部知识接入 · 聚焦本章的模块关系、源码依据与实现要点。

项目Dify 章节7.3 状态全文译文 模块认证、权限与安全、接口与服务契约、系统架构、界面与交互
项目要点页2.5 参考项目 项目章节目录Dify DeepWiki 原始章节MCP Protocol Integration 上一章7.2 下一章7.4
源码线索
  • api/controllers/console/workspace/tool_providers.py
  • api/core/mcp/client/sse_client.py
  • api/core/mcp/client/streamable_client.py
  • api/core/mcp/mcp_client.py
  • api/core/mcp/session/base_session.py
  • api/core/mcp/session/client_session.py
  • api/core/tools/entities/api_entities.py
  • api/core/tools/errors.py
  • api/core/tools/mcp_tool/provider.py
  • api/core/tools/tool_manager.py
模块标签
  • 认证、权限与安全
  • 接口与服务契约
  • 系统架构
  • 界面与交互
  • 测试、发布与运维

章节正文

MCP 协议集成

原始 DeepWiki 页面https://deepwiki.com/langgenius/dify/7.3-mcp-protocol-integration

MCP 协议集成

相关源文件

本章引用的主要源码文件：

  • api/controllers/console/workspace/tool_providers.py
  • api/core/mcp/client/sse_client.py
  • api/core/mcp/client/streamable_client.py
  • api/core/mcp/mcp_client.py
  • api/core/mcp/session/base_session.py
  • api/core/mcp/session/client_session.py
  • api/core/tools/entities/api_entities.py
  • api/core/tools/errors.py
  • api/core/tools/mcp_tool/provider.py
  • api/core/tools/tool_manager.py
  • api/services/tools/api_tools_manage_service.py
  • api/services/tools/builtin_tools_manage_service.py
  • api/services/tools/mcp_tools_manage_service.py
  • api/services/tools/tools_transform_service.py
  • api/services/tools/workflow_tools_manage_service.py
  • api/tests/test_containers_integration_tests/services/tools/__init__.py
  • api/tests/test_containers_integration_tests/services/tools/test_api_tools_manage_service.py
  • api/tests/unit_tests/services/tools/test_builtin_tools_manage_service.py
  • api/tests/unit_tests/services/tools/test_mcp_tools_transform.py
  • web/app/components/app/configuration/config-var/config-modal/__tests__/index.spec.tsx
  • web/app/components/app/configuration/tools/external-data-tool-modal.tsx
  • web/app/components/base/features/new-feature-panel/moderation/moderation-setting-modal.tsx
  • web/app/components/header/account-setting/__tests__/index.spec.tsx
  • web/app/components/header/account-setting/api-based-extension-page/empty.tsx
  • web/app/components/header/account-setting/index.tsx
  • web/app/components/header/account-setting/model-provider-page/provider-added-card/model-load-balancing-modal.tsx
  • web/app/components/tools/mcp/mcp-server-modal.tsx
  • web/app/components/tools/mcp/mcp-server-param-item.tsx
  • web/app/components/tools/mcp/modal.tsx
  • web/app/components/tools/types.ts
  • web/app/components/workflow/nodes/http/components/authorization/index.tsx

本文档描述了 Dify 中的模型上下文协议（MCP）集成，该集成支持从外部 MCP 兼容服务器动态发现和执行工具。MCP 提供了一种标准化方式来将能力暴露为工具，这些工具可以在 Agent 执行期间由大语言模型（LLM）调用。

关于其他工具提供者类型的信息，请参见 7.1 工具提供者类型与架构。关于内置和 API 工具集成的详细信息，请参见 7.2 内置和 API 工具集成。

MCP 协议概述

模型上下文协议是一种基于服务器的工具集成方法，其特点如下：

  • 外部 MCP 服务器通过标准端点公布其可用的工具和能力。
  • Dify 充当 MCP 客户端，连接这些服务器以动态发现工具。
  • 传输层（SSE/HTTP）处理 Dify 与 MCP 服务器之间的通信。
  • 认证在每个服务器上通过 API 密钥或 OAuth 2.0 流程进行处理。

来源：api/services/tools/mcp_tools_manage_service.py:78-80、api/core/mcp/session/base_session.py:13-32

系统架构与数据流

该集成将 Dify 的内部工具管理与外部 MCP 服务器连接起来。

代码实体空间到自然语言空间

下图将内部代码类和服务映射到高级 MCP 集成概念。

Dify · 代码实体空间到自然语言空间 · 图 1
Dify · 代码实体空间到自然语言空间 · 图 1

来源：api/core/tools/tool_manager.py:182-192、api/services/tools/mcp_tools_manage_service.py:78-82、api/core/mcp/client/streamable_client.py:77-80、api/core/mcp/session/base_session.py:123-136

数据库模型结构

MCPToolProvider 表

MCPToolProvider 模型存储 MCP 服务器配置、加密凭证以及已发现工具的缓存列表。

Dify · MCPToolProvider 表 · 图 2
Dify · MCPToolProvider 表 · 图 2

关键实现细节：

  • 加密：敏感字段（如 server_url、encrypted_credentials 和 encrypted_headers）在静态存储时使用租户特定密钥通过 encrypter.encrypt_token 进行加密 api/services/tools/mcp_tools_manage_service.py:150-151。
  • 工具缓存：已发现的工具以 JSON 字符串形式存储在 tools 列中，以避免在 Agent 执行期间重复进行发现调用 api/services/tools/mcp_tools_manage_service.py:33-33。

来源：api/services/tools/mcp_tools_manage_service.py:140-174、api/services/tools/mcp_tools_manage_service.py:1-26

MCP 客户端与传输

通信生命周期

Dify 使用专门的客户端栈来处理 MCP 通信，包括对过期令牌的自动重试。

Dify · 通信生命周期 · 图 3
Dify · 通信生命周期 · 图 3

关键组件：

  • MCPClient：实现模型上下文协议的核心逻辑 api/core/mcp/mcp_client.py:25-25。
  • BaseSession：实现 JSON-RPC 会话逻辑，包括通过 _response_streams 进行请求/响应链接，以及在 _receive_loop 中进行后台消息处理 api/core/mcp/session/base_session.py:138-163。
  • StreamableHTTPTransport：管理 HTTP/SSE 传输层，通过 mcp-session-id 请求头处理会话持久化 api/core/mcp/client/streamable_client.py:77-80、api/core/mcp/client/streamable_client.py:111-116。
  • MCPClientWithAuthRetry：一个包装器，用于捕获 MCPAuthError 或 MCPRefreshTokenError，并在重试操作前尝试刷新 OAuth 令牌 api/core/mcp/auth_client.py:19-21。

来源：api/core/mcp/client/streamable_client.py:44-51、api/core/mcp/client/streamable_client.py:150-159、api/core/mcp/session/base_session.py:123-143

工具发现与管理

提供者注册

当用户添加 MCP 提供者时，MCPToolManageService 会执行以下步骤：

  1. 校验：校验 URL 格式，并使用 server_url_hash 检查重复项 api/services/tools/mcp_tools_manage_service.py:141-148。
  2. 加密：加密 URL、请求头以及任何初始凭证 api/services/tools/mcp_tools_manage_service.py:150-157。
  3. 持久化：保存 MCPToolProvider 记录 api/services/tools/mcp_tools_manage_service.py:160-177。
工具转换

Dify 将 MCP 原生工具定义转换为其内部 ToolApiEntity 格式，以确保在用户界面和 Agent 引擎之间的一致性。

  • ToolTransformService.mcp_provider_to_user_provider：将数据库模型转换为高级 API 实体 api/services/tools/mcp_tools_manage_service.py:179-179。
  • _mcp_tools_adapter：一个 Pydantic 类型适配器，用于解析 MCP 服务器返回的 JSON 工具定义 api/services/tools/tools_transform_service.py:34-34。

来源：api/services/tools/mcp_tools_manage_service.py:139-180、api/services/tools/tools_transform_service.py:34-38

认证流程

MCP 集成支持复杂的认证场景，包括 OAuth 2.0 和自定义请求头。

OAuth 生命周期
  1. 启动：auth() 流程启动握手，可能使用 PKCE api/controllers/console/workspace/tool_providers.py:23-24。
  2. 存储：令牌和客户端信息被加密并存储为 OAuthDataType api/services/tools/mcp_tools_manage_service.py:37-43。
  3. 重试逻辑：MCPClientWithAuthRetry 在 MCP 服务器返回 401/403 错误时处理自动令牌刷新 api/core/mcp/auth_client.py:19-21。

来源：api/controllers/console/workspace/tool_providers.py:226-233、api/services/tools/mcp_tools_manage_service.py:37-43

安全与隔离

  • SSRF 保护：MCP 请求通过 create_ssrf_proxy_mcp_http_client 和 ssrf_proxy_sse_connect 进行路由，以防止内部网络扫描 api/core/mcp/client/streamable_client.py:33-33。
  • 多租户：所有 MCP 查询都严格按 tenant_id 进行范围限定 api/services/tools/mcp_tools_manage_service.py:86-115。
  • 敏感数据：在 API 响应中使用 UNCHANGED_SERVER_URL_PLACEHOLDER（[__HIDDEN__]），以防止在更新期间将加密的 URL 泄露回前端 api/services/tools/mcp_tools_manage_service.py:31-31。

来源：api/services/tools/mcp_tools_manage_service.py:31-31、api/services/tools/mcp_tools_manage_service.py:86-115、api/core/mcp/client/streamable_client.py:33-35