Yuxi 平台 MCP 集成指南：远程服务器接入、内置 stdio 管理与安全边界

Yuxi 平台 MCP 集成指南远程服务器接入、内置 stdio 管理与安全边界【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/YuxiMCPModel Context Protocol让 Yuxi 智能体能够调用外部服务提供的工具是连接知识智能体与外部能力的关键桥梁。本文基于 docs/agents/mcp-integration.md 并结合仓库源码系统讲解 Yuxi 中 MCP 的三种传输方式、远程服务器的接入流程、智能体绑定规则、内置 stdio MCP 的代码维护方式以及贯穿全流程的安全边界读完即可在私有部署环境中完成 MCP 服务器的添加、验证、授权与工具级管控。MCP 在 Yuxi 中的角色与支持的传输方式在 Yuxi 中MCP 的职责划分很清晰管理员在扩展 → MCP中添加远程服务器智能体配置再决定哪些服务器进入运行时。即服务器管理与智能体使用是两层独立的配置前者由管理接口维护后者在智能体配置的 MCP 字段中声明。Yuxi 支持三种传输方式适用场景各不相同传输方式适用场景streamable_http新的远程 MCP 服务推荐sse仍提供 SSE 接口的远程服务stdio仅限代码维护的系统内置 MCP其中管理接口只接受streamable_http和sse。这一点在源码中有双重约束路由层在create_mcp_server_route中校验valid_transports (sse, streamable_http)业务层在create_mcp_server中再次校验transport not in _USER_CONFIGURABLE_TRANSPORTS即抛出ValueError(用户创建的 MCP 仅支持 sse 或 streamable_http不允许启动 stdio 本地进程)对应实现见 mcp_router.py 与 service.py。Yuxi 不允许通过 HTTP 请求创建任意本地stdio进程。对历史遗留的用户stdio配置启动时会由ensure_builtin_mcp_servers_in_db统一禁用enabled置 0updated_by记为system必须迁移为远程服务后才能重新启用set_server_enabled中对这类待迁移服务器启用时会直接拒绝提示改为 sse 或 streamable_http见 service.py 与 service.py。添加远程 MCP管理页与 HTTP 接口在扩展 → MCP点击添加 MCP需要填写四个核心信息稳定标识slug、名称、传输方式、URL。其中slug是唯一标识一旦创建即作为后续所有管理操作启用/禁用、测试、工具管理的定位键创建后不可变更因此建议使用语义稳定、全局唯一的命名例如custom-remote-mcp。一个典型的添加配置{ slug: custom-remote-mcp, name: Example MCP, transport: streamable_http, url: https://example.com/mcp }管理接口对应的是POST /api/system/mcp-servers Authorization: Bearer admin-token Content-Type: application/json { slug: custom-remote-mcp, name: Example MCP, transport: streamable_http, url: https://example.com/mcp, description: 提供示例查询工具 }除上述字段外请求体还支持以下可选字段字段定义见 mcp_router.py 中的CreateMcpServerRequest字段类型含义slugstring稳定标识唯一、创建后不可修改namestring展示名称transportstring传输类型仅sse/streamable_httpurlstring服务器 URLsse/streamable_http 传输类型下必填descriptionstring描述便于其他管理员识别用途headersobjectHTTP 请求头用于携带认证凭证timeoutintHTTP 超时时间秒sse_read_timeoutintSSE 读取超时秒tagsarray标签数组用于 UI 分类展示iconstring图标emoji注意请求体使用ConfigDict(extraforbid)多余字段会被拒绝且该接口要求管理员身份get_admin_user依赖。需要认证的远程服务可以通过headers配置 HTTP 请求头同时按需设置timeoutHTTP 超时与sse_read_timeoutSSE 读取超时。凭证会随着连接请求发送因此务必遵守两条原则只配置必要的 header避免把无关的内部凭证也带上把管理接口限制在可信的管理员范围普通用户调用GET /api/system/mcp-servers只能看到脱敏的基础信息name、description、icon、enabled、tags见 mcp_router.py。添加后的推荐流程是先点击测试连接对应POST /api/system/mcp-servers/{slug}/test确认能发现工具再把服务器状态设为已添加。状态关闭时enabled0服务器记录仍保留但不会进入运行时——_load_enabled_mcp_server_configs的查询条件即MCPServer.enabled 1见 service.py。让智能体使用 MCP绑定规则与工具级管控服务器已添加之后还需要在智能体配置的 MCP 字段中显式选择或者依赖默认规则。运行时解析逻辑在resolve_configured_runtime_tools中实现见 toolkits/service.py规则如下未显式配置时使用当前用户可见的全部已启用服务器显式选择后只使用选择项且会按配置顺序去重selected_mcp_servers集合去重MCP 工具仍会在执行处使用当前用户身份和服务器配置管理员可以在 MCP 详情页单独禁用某个工具禁用列表disabled_tools随配置下发给运行时过滤。工具级禁用由toggle_tool_enabled实现在server.disabled_tools列表中添加或移除工具名并清理该服务器的工具缓存见 service.py。注意工具禁用只影响返回值过滤不会影响 MCP 客户端的建连参数。配置读取与缓存机制源码原理MCP 配置从 PostgreSQL 的mcp_servers表读取模型定义见 models_business.py工具对象则按配置哈希缓存在进程内存中。核心流程在get_mcp_tools从数据库读取该服务器的启用配置若不存在或已禁用则返回空列表将完整配置json.dumps后做 SHA-256 哈希取前 16 位作为缓存键{server_slug}:{config_hash}若缓存键未命中或强制刷新通过MultiServerMCPClient来自langchain_mcp_adapters建立连接并拉取全部工具工具缓存更新时会顺带清理同一server_slug的旧缓存键避免内存膨胀。因此修改连接配置或工具禁用列表后下一次运行会使用新的配置键自动触发工具重建无需重启服务。对应实现见 service.py。此外每个拉取到的工具都会被赋予一个全局唯一 ID格式为mcp__{server_cc}__{tool_cc}其中server_cc、tool_cc是将 slug 与工具名转为 lowerCamelCase 的结果见to_camel_case并设置tool.handle_tool_error True确保工具调用抛出ToolException时不会击穿服务见 service.py 与 service.py。该唯一 ID 也是管理端工具列表GET /api/system/mcp-servers/{slug}/tools中id字段的取值来源。多服务器并发加载当智能体配置了多个 MCP 服务器时工具加载采用asyncio.gather并发方式单服务器连接约 33-300ms串行会累积延迟并发取 max 而非 sum单个服务器失败仅告警并跳过不影响其余服务器见 toolkits/service.py。Skill 依赖的 MCP 工具同样走并发加载路径见 middlewares/skills.py。添加内置 stdio MCP代码维护与数据库同步stdioMCP 等价于在 API/worker 容器内启动一个本地进程只适合经过代码审查且必须本地运行的系统能力。远程服务可以承载时优先使用 SSE 或 Streamable HTTP。在内置定义中注册开发者在service.py的_DEFAULT_MCP_SERVERS中添加固定定义。仓库当前内置示例为图表生成工具mcp-server-chart_DEFAULT_MCP_SERVERS { mcp-server-chart: { command: npx, args: [-y, antv/mcp-server-chart], transport: stdio, description: 图表生成工具支持生成各类图表柱状图、折线图、饼图等, icon: , tags: [内置, 图表], }, }新增内置定义时command、args和env必须是代码中的固定值包版本必须锁定例如scope/example-mcp1.2.3不能从 HTTP 请求、数据库字段或不受信任的环境拼接。env只放非敏感固定值密钥不能提交到代码或同步到数据库。启动时的同步与治理逻辑API/worker 启动时调用ensure_builtin_mcp_servers_in_db完成三类治理见 service.py禁用历史用户 stdio 配置把非内置 slug、transport stdio且处于启用状态enabled 1的服务器全部置为禁用并记录updated_by system清理退役内置项_RETIRED_BUILTIN_MCP_SERVER_SLUGS中列出的旧内置仓库当前为sequentialthinking若由system创建则从数据库删除同步/新增内置定义对_DEFAULT_MCP_SERVERS中的每个 slug不存在则插入enabled0、created_bysystem已存在则按_SYNCED_MCP_FIELDSdescription、transport、url、command、args、env、headers、timeout、sse_read_timeout、tags、icon比对更新。由此得到的运行规则是新内置 MCP 默认未添加enabled0管理员需要在管理页显式启用内置项的连接配置由代码维护不能通过接口删除is_builtin_mcp_server检查后返回 403、也不能通过页面改成其他进程update_mcp_server对内置项抛PermissionError运行时配置以代码为准_to_runtime_mcp_config对内置项总是从_DEFAULT_MCP_SERVERS取连接字段仅叠加数据库中的disabled_tools见 service.py。验证新内置 MCP修改代码后重新构建并观察日志docker compose up -d --build api worker docker compose logs --tail100 api worker日志中应出现类似Added built-in MCP server slug to database或字段同步的更新记录。随后在管理页添加并测试工具。测试只确认连接和工具发现不要在没有隔离和授权的情况下执行文件写入、Shell 或其他副作用。安全边界MCP 副作用的等同性与凭证隔离::: danger 安全边界 MCP 工具的副作用等同于外部服务或本地进程本身的副作用。审查依赖来源、固定版本、命令参数、网络访问和数据权限不要把SANDBOX_PROVISIONER_TOKEN、数据库密码或对象存储管理凭据注入 MCP 或 Agent 沙盒。 :::这条边界在仓库中有直接的测试用例背书test_mcp_stdio_security.py 验证了两类关键行为——stdio 恶意载荷被拒绝且无副作用向/api/system/mcp-servers提交command/args指向本地命令的 stdio 配置会被接口拒绝400并断言 API 容器内未产生文件stdio MCP payload created a file in the API container历史 stdio 配置被禁用且不启动进程预置 legacy stdio 记录后调用ensure_builtin_mcp_servers_in_db断言该服务器工具加载结果为空、enabled被置 0且/test接口拒绝连接。实操层面的安全清单可归纳为只给 MCP 配置必要的 header密钥走环境变量或密钥管理而非配置明文stdio 只允许经过代码审查的内置项测试连接时避免触发有副作用的工具调用。常用管理接口速查方法路径作用GET/api/system/mcp-servers查看服务器普通用户只得到脱敏基础信息POST/PUT/api/system/mcp-servers、/{slug}添加或修改远程 MCPPUT/api/system/mcp-servers/{slug}/status添加或移除服务器切换enabledPOST/api/system/mcp-servers/{slug}/test测试连接并发现工具GET/api/system/mcp-servers/{slug}/tools查看工具含参数 schema 与启用状态POST/api/system/mcp-servers/{slug}/tools/refresh刷新工具列表清除缓存重新获取PUT/api/system/mcp-servers/{slug}/tools/{tool_name}/toggle启用或禁用单个工具所有接口定义在 mcp_router.py路由前缀为/system/mcp-servers其中写操作POST/PUT/DELETE均要求管理员身份。接口字段和错误响应的最终定义以实例 Swagger 为准。小结Yuxi 的 MCP 集成形成了一条完整、可审计的链路管理接口只允许远程传输sse / streamable_http→ 内置 stdio 由代码固定定义并同步数据库 → 智能体按配置绑定已启用服务器 → 工具按配置哈希缓存并按 disabled_tools 过滤 → 全程拒绝任意本地进程启动。对私有部署场景这套设计在外部能力接入与进程与凭证安全之间取得了明确平衡远程服务负责业务扩展本地进程只留给经过审查的内置能力。【免费下载链接】Yuxi可私有部署的多租户知识智能体平台统一 RAG、知识图谱、多智能体、MCP/Skills、沙盒与权限管理。Self-hosted knowledge agent platform for RAG, knowledge graphs and multi-agent workflows.项目地址: https://gitcode.com/GitHub_Trending/yu/Yuxi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考