agentic_huge_data_base / wiki
页面 Onyx · 12.5 MCP 服务端与外部集成·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 12.5

12.5 · MCP 服务端与外部集成

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节12.5 状态全文译文 模块界面与交互、认证、权限与安全、系统架构、接口与服务契约
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节MCP Server and External Integrations 上一章12.4 下一章12.6
源码线索
  • backend/alembic/versions/0816326d83aa_add_federated_connector_tables.py
  • backend/ee/onyx/onyxbot/slack/handlers/handle_standard_answers.py
  • backend/ee/onyx/utils/encryption.py
  • backend/onyx/context/search/federated/models.py
  • backend/onyx/context/search/federated/slack_search.py
  • backend/onyx/context/search/federated/slack_search_utils.py
  • backend/onyx/db/federated.py
  • backend/onyx/db/rotate_encryption_key.py
  • backend/onyx/db/slack_channel_config.py
  • backend/onyx/federated_connectors/federated_retrieval.py
模块标签
  • 界面与交互
  • 认证、权限与安全
  • 系统架构
  • 接口与服务契约
  • 文档对象与元数据

章节正文

MCP 服务端与外部集成

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/12.5-mcp-server-and-external-integrations

MCP 服务器与外部集成

相关源文件

以下文件为本维基页面的生成提供了上下文：

  • backend/alembic/versions/0816326d83aa_add_federated_connector_tables.py
  • backend/ee/onyx/onyxbot/slack/handlers/handle_standard_answers.py
  • backend/ee/onyx/utils/encryption.py
  • backend/onyx/context/search/federated/models.py
  • backend/onyx/context/search/federated/slack_search.py
  • backend/onyx/context/search/federated/slack_search_utils.py
  • backend/onyx/db/federated.py
  • backend/onyx/db/rotate_encryption_key.py
  • backend/onyx/db/slack_channel_config.py
  • backend/onyx/federated_connectors/federated_retrieval.py
  • backend/onyx/federated_connectors/interfaces.py
  • backend/onyx/federated_connectors/slack/federated_connector.py
  • backend/onyx/onyxbot/slack/blocks.py
  • backend/onyx/onyxbot/slack/formatting.py
  • backend/onyx/onyxbot/slack/handlers/handle_buttons.py
  • backend/onyx/onyxbot/slack/handlers/handle_message.py
  • backend/onyx/onyxbot/slack/handlers/handle_regular_answer.py
  • backend/onyx/onyxbot/slack/listener.py
  • backend/onyx/onyxbot/slack/models.py
  • backend/onyx/onyxbot/slack/utils.py
  • backend/onyx/prompts/federated_search.py
  • backend/onyx/server/features/mcp/api.py
  • backend/onyx/server/features/mcp/models.py
  • backend/onyx/server/federated/api.py
  • backend/onyx/server/federated/models.py
  • backend/onyx/server/manage/slack_bot.py
  • backend/onyx/utils/encryption.py
  • backend/scripts/reencrypt_secrets.py
  • backend/tests/external_dependency_unit/db/test_rotate_encryption_key.py
  • backend/tests/external_dependency_unit/slack_bot/test_slack_bot_federated_search.py
  • backend/tests/integration/tests/mcp/test_mcp_client_no_auth_flow.py
  • backend/tests/unit/ee/onyx/utils/test_encryption.py
  • backend/tests/unit/federated_connector/test_reject_masked_credentials.py
  • backend/tests/unit/onyx/context/search/federated/test_build_thread_text.py
  • backend/tests/unit/onyx/context/search/federated/test_url_override.py
  • backend/tests/unit/onyx/onyxbot/test_slack_channel_config.py
  • backend/tests/unit/onyx/onyxbot/test_slack_formatting.py
  • backend/tests/unit/onyx/server/features/mcp/test_oauth_credentials_resolver.py
  • [web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigCreationForm.tsx](web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigCreationForm.tsx)
  • [web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigFormFields.tsx](web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigFormFields.tsx)
  • [web/src/app/admin/bots/[bot-id]/lib.ts](web/src/app/admin/bots/[bot-id]/lib.ts)
  • web/src/components/ui/accordion.tsx
  • web/src/lib/tools/mcpService.ts
  • web/src/lib/tools/openApiService.ts

Onyx 提供了一套集成层，用于将知识库扩展到 Web 应用程序之外。这包括一个用于大语言模型（LLM）原生工具访问的 模型上下文协议（MCP）服务器、一个用于在工作区频道内进行对话式检索增强生成（RAG）的全面 Slack 集成（OnyxBot），以及用于从外部平台实时检索数据的 联合搜索 功能。

MCP 服务器

Onyx MCP 服务器实现了模型上下文协议，允许外部大语言模型（LLM）客户端（例如 Claude Desktop）将 Onyx 作为知识源使用。它充当了 Onyx 后端与任何支持 MCP 标准的大语言模型（LLM）客户端之间的桥梁。

可用工具与资源

MCP 服务器将多个核心功能作为工具暴露出来，这些工具会被动态构建并提供给大语言模型（LLM）。在 Onyx 中，该服务器支持标准的工具发现功能，以及基于 OAuth 的外部 MCP 服务器认证 backend/onyx/server/features/mcp/api.py:81-82。

关键能力包括：

  • 搜索已索引文档：对 Onyx 中索引的所有文档执行语义搜索。
  • 网络搜索：利用 Onyx 的网络搜索能力，查找内部索引之外的信息。
  • 打开 URL：获取并解析特定 URL 的内容，为大语言模型（LLM）提供直接上下文。
配置与认证

MCP 服务器通过环境变量进行控制，并使用标准的 Onyx 认证机制。管理员用户可以通过 API 配置 MCP 服务器，支持不同的认证执行者（用户或管理员）和认证类型（API 密钥、OAuth）backend/onyx/server/features/mcp/api.py:34-37。

  • 认证：通过个人访问令牌（PAT）或 API 密钥进行处理。该服务器支持 OAuth 流程，包括回调处理和令牌存储 backend/onyx/server/features/mcp/api.py:17-21。
  • 权限：对 MCP 配置和工具管理的访问权限仅限于管理员或审核员 backend/onyx/server/features/mcp/api.py:30。

来源： backend/onyx/server/features/mcp/api.py backend/onyx/server/features/mcp/models.py

OnyxBot Slack 集成

OnyxBot 是一个专门的 Slack 集成，允许用户直接从 Slack 查询其知识库。它支持多种响应模式，包括公共频道回复、临时（私有）回复和直接消息。

系统架构与数据流

Slack 集成作为后台进程运行，使用 SocketModeClient 监听来自 Slack API 的事件，无需公开的 Webhook URL backend/onyx/onyxbot/slack/utils.py:19。

关键组件：
  • SlackbotHandler：主要编排器，负责管理特定租户的 Socket 连接和令牌生命周期 backend/onyx/onyxbot/slack/listener.py:136-146。它处理租户锁的获取，以确保跨多个 Pod 的高可用性 backend/onyx/onyxbot/slack/listener.py:144。
  • TenantSocketModeClient：一个专用客户端，用于维护特定租户和机器人实例与 Slack 的连接 backend/onyx/onyxbot/slack/listener.py:88。
  • handle_message：处理传入 Slack 事件的主要入口点，应用过滤器并确定是否需要响应 backend/onyx/onyxbot/slack/handlers/handle_message.py:112-117。
消息处理管线

当收到消息时，OnyxBot 会执行以下流程：

  1. 事件确认：立即确认请求，通常会回复一个表情符号反应或一条“正在处理”的消息 backend/onyx/onyxbot/slack/handlers/handle_message.py:30-47。
  2. 过滤器校验：检查消息是否满足 ChannelConfig 中定义的条件，例如 respond_tag_only 或 respond_member_group_list backend/onyx/onyxbot/slack/handlers/handle_message.py:157-175。
  3. 上下文构建：使用 read_slack_thread 收集线程历史，为大语言模型（LLM）提供对话上下文 backend/onyx/onyxbot/slack/handlers/handle_buttons.py:137-143。
  4. 检索增强生成（RAG）执行：调用 handle_regular_answer，该函数运行核心搜索管线和大语言模型（LLM）循环，基于索引文档生成答案 backend/onyx/onyxbot/slack/handlers/handle_regular_answer.py:137-148。
  5. 响应格式化：将大语言模型（LLM）响应转换为 Slack 块，包括引用和交互式反馈按钮（赞/踩）backend/onyx/onyxbot/slack/blocks.py:106-123。
Slack 机器人配置逻辑

下图说明了 Slack 配置如何从数据库映射到执行逻辑。

Slack 实体关系图

Onyx · Slack 机器人配置逻辑 · 图 1
Onyx · Slack 机器人配置逻辑 · 图 1

来源： backend/onyx/onyxbot/slack/listener.py backend/onyx/onyxbot/slack/handlers/handle_message.py backend/onyx/onyxbot/slack/handlers/handle_regular_answer.py backend/onyx/server/manage/slack_bot.py web/src/app/admin/bots/[bot-id]/channels/SlackChannelConfigFormFields.tsx

联合搜索

联合搜索允许 Onyx 在聊天会话期间实时查询外部系统，而不仅仅依赖预先索引的数据。这对于像 Slack 消息这样的高频数据特别有用。

实现：Slack 联合搜索

Slack 的联合检索系统利用 Slack 搜索 API，在公共和私有频道（在允许的情况下）中查找相关消息。

关键特性：
  • 动态查询扩展：使用大语言模型（LLM）将用户的自然语言查询扩展为多个优化的 Slack 搜索词 backend/onyx/context/search/federated/slack_search_utils.py:22。
  • 日期范围提取：从查询中启发式地提取时间范围（例如“今天”、“上周”），以过滤 Slack 结果 backend/onyx/context/search/federated/slack_search_utils.py:142-196。
  • 元数据缓存：将频道元数据缓存到 Redis 中最多 24 小时，以减少 API 开销 backend/onyx/context/search/federated/slack_search.py:57-78。
  • 线程上下文：可以获取已发现消息的完整线程上下文，以提供更好的检索增强生成（RAG）上下文 backend/onyx/context/search/federated/slack_search.py:16-17。
联合搜索的数据流

下图展示了使用 slack_search 实现从用户查询到外部结果的流程。

联合搜索执行流程

Onyx · 联合搜索的数据流 · 图 2
Onyx · 联合搜索的数据流 · 图 2

来源： backend/onyx/context/search/federated/slack_search.py backend/onyx/context/search/federated/slack_search_utils.py backend/onyx/onyxbot/slack/utils.py

配置摘要

环境变量描述默认值
MCP_SERVER_ENABLED启用模型上下文协议服务器False
MCP_SERVER_PORTMCP 服务器的端口5001
NOTIFY_SLACKBOT_NO_ANSWER当机器人无法找到答案时是否通知 backend/onyx/onyxbot/slack/listener.py:35True
ONYX_BOT_FEEDBACK_REMINDER在 Slack 中发送反馈提醒前等待的分钟数 backend/onyx/onyxbot/slack/handlers/handle_message.py:69None
MAX_TENANTS_PER_POD单个 Slack 机器人监听器 Pod 处理的最大租户数 backend/onyx/onyxbot/slack/config.py:4950

来源：

  • backend/onyx/onyxbot/slack/listener.py
  • backend/onyx/onyxbot/slack/config.py
  • backend/onyx/onyxbot/slack/handlers/handle_message.py