企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 编排
• 低代码
• AI 技能
• RAG

MCP（Model Context Protocol）是当前 AI 工具服务间通信的标准协议。Nexent 平台原生支持将符合 MCP 规范的各类工具服务接入 Agent，从而大幅扩展 Agent 的能力边界。本文将基于 MCP Service Integration 文档，结合 Nexent 仓库中 MCP 服务层、OpenAPI 转换层与容器管理的真实实现，系统讲解远程 URL、容器、API-to-MCP 三种集成方式的操作步骤、配置参数与底层原理，读完你即可独立完成 MCP 服务的接入、管理、发布与 Agent 工具绑定。

MCP 与 Nexent 的集成关系

Nexent 的 MCP 能力建立在fastmcp之上，核心运行实体在 backend/mcp_service.py 中维护，代码注释将其架构描述为"分层代理架构"（hierarchical proxy architecture）：

• 本地服务层（local service layer）：稳定的本地挂载服务，对应 backend/tool_collection/mcp/local_mcp_service.py，挂载了 nl2agent 等本地 MCP 服务；
• 远程代理层（remote proxy layer）：动态托管的远程 MCP 服务代理，负责与外部 MCP Server 建立连接；
• 外接 API 层（outer_api layer）：动态注册的外接 API 工具，即下文要重点讲解的 API-to-MCP 转换结果。

Nexent 目前支持三种 MCP 服务集成方式，选择依据如下：

方式一：通过 Remote URL 集成远程 MCP 服务

Remote URL 方式适合接入独立部署的 MCP 服务，例如 ModelScope 等平台托管的公共 MCP 服务。

操作步骤

1. 进入MCP Repository（MCP 仓库）→ My MCP页面；
2. 点击Add MCP Service（添加 MCP 服务）；
3. 集成类型选择Remote（远程）；
4. 填写服务配置：

5. 点击Connectivity Test（连通性测试），确认服务可达；
6. 点击Save（保存），完成添加。

连通性测试的底层实现

文档中强调的"Connectivity Test"并非简单的 ping，而是执行一次真实的 MCP 协议握手。在 backend/services/remote_mcp_service.py 中，test_mcp_connection()会调用_mcp_protocol_connect()：若 URL 以/sse结尾则使用SSETransport，否则使用StreamableHttpTransport，随后执行 MCPinitialize握手并尝试建立客户端连接。值得注意的是，这个测试只做初始化握手、不调用 list_tools()，因此比完整健康检查（mcp_server_health()）更轻量、更快。同时，add_remote_mcp_server_list()在落库前也会通过_mcp_protocol_health_check()拉取工具列表，验证不通过会直接抛出MCPConnectionError，避免无效配置被保存。

示例：接入 ModelScope GitHub MCP

ModelScope 提供了丰富的 MCP 服务，接入 GitHub MCP 的典型流程如下：

1. 访问 ModelScope MCP 市场，找到 GitHub MCP；
2. 获取其 SSE 端点地址；
3. 在 Nexent 中填写如下配置：

{ "name": "modelscope-github", "url": "https://api.modelscope.cn/mcp/servers/github", "headers": {} }

4. 连通性测试通过后即可在 Agent 工具列表中选用。

方式二：通过 Container 集成容器化 MCP 服务

Container 方式适合以 Docker 容器方式运行的 MCP 服务，例如通过npx启动的各类 MCP Server。

操作步骤

1. 进入MCP Repository → My MCP页面；
2. 点击Add MCP Service；
3. 集成类型选择Container（容器）；
4. 填写容器配置 JSON：

{ "mcpServers": { "service-name": { "command": "npx", "args": ["-y", "@modelScope/mcp-server-package@version"] } } }

5. 填写容器端口号；
6. 点击Save，系统会自动启动容器并完成配置。

容器启动与端口分配原理

容器启动并非直接运行原始命令，而是通过mcp_proxy代理进程包装。从 backend/services/remote_mcp_service.py 的add_container_mcp_service()可以看到，实际执行的完整命令为：

python -m mcp_proxy --host 0.0.0.0 --port <port> --transport streamablehttp -- <command> <args...>

即：容器内部以streamablehttp传输方式暴露 MCP 端点，代理外部请求到内部真实命令。该函数还会做多项前置校验：

• MCP 名称不能与租户内已启用服务冲突（McpNameConflictError）；
• 端口必须可用：check_container_port_conflict()同时检查数据库中的已占用记录与宿主机实际监听状态（含 IPv4 / IPv6 与host.docker.internal探测）；
• 容器配置必须恰好包含一个mcpServers条目（McpValidationError）；
• 拒绝docker作为内部命令（防止嵌套容器逃逸）。

容器编排统一交给 backend/services/mcp_container_service.py 的MCPContainerManager，该管理器根据部署环境自动选择 Docker 或 Kubernetes 客户端，并支持通过.tar镜像文件直接导入（即文档提到的Local Image Upload 本地镜像上传方式，需管理员在部署中开启Upload Image功能）。

端口规则说明

• Docker / Kubernetes 部署：容器端口由系统统一分配并锁定，不可手动修改；多个 MCP 服务可复用同一默认端口而不冲突；
• 本地部署：端口由用户指定，可点击Recommended Port（推荐端口）一键获取可用端口（源码中suggest_container_port()会在 2000～50000 范围内随机探测可用端口），系统会自动检测端口占用。

方式三：通过 API-to-MCP 将 REST API 转换为 MCP 工具

这是 Nexent 提供的重量级能力：无需编写任何 MCP Server 代码，即可将现有 REST API 快速转换为 MCP 工具，让 Agent 直接以自然语言调用企业内部接口。

典型适用场景

• 企业已有 REST API 接口，希望快速赋予 Agent 调用能力；
• 第三方服务只提供 HTTP API、没有现成 MCP 适配器；
• 需要快速原型验证，将 API 能力暴露给 Agent。

操作步骤

1. 进入Agent Development（Agent 开发）→ MCP Configuration；
2. 集成类型选择API to MCP；
3. 填写配置：

4. 点击Add（添加）完成转换。

支持的 OpenAPI 3.x 特性

转换功能支持以下 OpenAPI 3.x 特性：

• HTTP 方法：GET / POST / PUT / DELETE；
• Path、Query、Header 三类参数；
• Request Body（JSON 格式）；
• 认证信息：Bearer Token、API Key（Query / Header）、Basic Auth。

源码级实现：从 OpenAPI 到 MCP 的完整链路

API-to-MCP 的核心实现分布在服务层与数据库层，整体链路清晰：

1. 导入与持久化：backend/services/tool_configuration_service.py 的import_openapi_service()负责导入——若未显式提供service_description，会自动从openapi_json.info.description提取，缺失时回退到info.title；同时会把servers覆盖为填写的 Base Service URL。随后通过 backend/database/outer_api_tool_db.py 的upsert_openapi_service()落库。数据库模型为OuterApiService，以服务为单位存一条记录（而非每个工具一条），并采用delete_flag软删除机制保证审计可追溯。

2. 注册到 MCP 运行时：落库后，工具配置应用 backend/apps/tool_config_app.py 会调用_refresh_openapi_services_in_mcp()，通过 HTTP 通知 MCP 管理服务（端口 5015）执行刷新（最多重试 3 次）。MCP 服务端 backend/mcp_service.py 的register_openapi_service()则调用FastMCP.from_openapi()一次性批量加载规范中的全部工具，并用httpx.AsyncClient（默认 120 秒超时）作为底层 REST 客户端。

3. 多租户隔离：转换得到的工具按租户隔离。refresh_openapi_services_by_tenant()会为每个租户构建独立的FastMCP实例（nexent_mcp_{tenant_id}），先离线构建完整副本、全部注册成功后再原子发布，避免刷新过程中影响正在使用的客户端。对外通过TenantMCPRouter以/mcp/{tenant_id}/sse路由分发（SSE 服务端口 5011），并校验Authorization与租户身份，未授权请求返回 403。

4. 工具同步：导入成功并刷新 MCP 运行时后，还会调用update_tool_list()将新工具同步到持久化工具列表——因为 Agent 配置页读取的是持久化工具列表，仅刷新 MCP 运行时并不能让新工具立即可选（见 backend/apps/tool_config_app.py 中导入接口的注释说明）。

示例：将内部工单系统转换为 MCP

假设你有一个工单系统，其 OpenAPI 定义如下：

{ "openapi": "3.0.0", "info": {"title": "Ticket System", "version": "1.0.0"}, "paths": { "/tickets": { "get": { "summary": "Get ticket list", "parameters": [ {"name": "status", "in": "query", "schema": {"type": "string"}} ] }, "post": { "summary": "Create ticket", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": {"type": "string"}, "description": {"type": "string"} } } } } } } } } }

完成转换后，Agent 即可通过自然语言调用这些接口，例如"查询所有待处理的工单"。转换后的工具名会经过_sanitize_function_name()清洗为合法的 MCP 工具标识符（非法字符替换为下划线、纯数字开头补tool_前缀）。

关于实现正确性的保障：仓库测试 test/backend/services/test_mcp_service.py 覆盖了register_openapi_service的成功注册、重复注册跳过、空名称拒绝、OpenAPI 规范深拷贝不被篡改、headers 模板传递等场景；test/backend/services/test_tool_configuration_service.py 覆盖了import_openapi_service对 description 的提取回退逻辑与headers_template透传。

管理已集成的 MCP 服务

查看服务状态

My MCP 中每个服务卡片展示以下状态：

（详见 MCP Repository 管理文档，该文档还补充了角色差异：开发者可见 Repository / My MCP 两个标签页，管理员额外可见 Review Center 审核中心。）

常用操作

• Edit（编辑）：修改服务名称、描述、URL、Authorization Token、标签等配置；
• Enable / Disable（启用/停用）：通过开关控制服务状态；
• Connectivity Test（连通性测试）：测试服务连接状态；
• View Tool List（查看工具列表）：查看服务提供的全部工具；
• Container Management（容器管理）：查看容器日志与创建时的配置 JSON（仅容器化服务）；
• Apply to Publish（申请发布）：将服务共享给同租户成员；发布前至少勾选一项需共享的配置字段，并可填写发布说明；
• View Review Progress（查看审核进度）：查看申请状态，可取消申请或下架服务；
• Delete（删除）：删除服务；容器类服务会同时清理对应容器资源。

在 Agent 中使用 MCP 工具

工具分配

1. 进入Agent Development页面；
2. 在Select Agent's Tools（选择 Agent 工具）中切换到MCP标签页；
3. 找到已添加的 MCP 服务，展开查看工具列表；
4. 勾选所需工具并配置必要参数；
5. 保存 Agent 配置。

分配时后端会读取租户下所有已启用且健康的 MCP 记录，逐一拉取工具元数据，并将本地挂载的outer-apis（API-to-MCP 转换结果）合并进工具列表（见 backend/services/tool_configuration_service.py 的get_all_mcp_tools()）。

工具测试

分配工具时，可点击工具卡片上的Test（测试）按钮验证功能：

1. 填写测试参数；
2. 点击Execute Test（执行测试）；
3. 查看返回结果。

最佳实践

安全建议

1. 保护认证信息：优先使用平台的密钥管理能力，避免在配置中以明文存储 Token；
2. 最小权限原则：只为服务申请运行所需的最小权限；
3. 定期轮换：定期更换 API Key 等认证信息。

性能建议

1. 服务可用性：确保 MCP 服务稳定可靠，避免拖慢 Agent 响应；
2. 超时设置：为耗时操作设置合理的超时时间（源码中 API 转换服务的 HTTP 客户端默认超时为 120 秒）；
3. 错误处理：善用工具测试提前发现并处理问题。

维护建议

1. 版本管理：跟进 MCP 服务更新，及时升级到稳定版本；
2. 日志监控：监控服务调用日志，及时处理异常；
3. 依赖管理：记录服务依赖关系，便于故障排查。

FAQ

Q：MCP 服务连接失败怎么办？

1. 检查服务 URL 是否可访问；
2. 确认网络连通性与防火墙配置；
3. 核对认证信息是否正确；
4. 检查服务是否正常运行。

Q：API-to-MCP 支持哪些认证方式？

目前支持：

• Bearer Token
• API Key（Query / Header）
• Basic Auth

Q：如何开发自己的 MCP 服务？

Nexent 仓库中fastmcp风格的 MCP 服务实现可参考 backend/tool_collection/mcp 目录下的本地服务代码；容器类 MCP 服务则通过mcp_proxy包装后统一以streamablehttp传输接入。容器化部署中如需访问 Docker，需要挂载/var/run/docker.sock（见 backend/services/mcp_container_service.py 的注释说明）。

相关资源

• MCP Repository 管理文档 — 浏览、安装与管理 MCP 服务（含发布审核流程）
• Agent 配置文档 — 在 Agent 中使用 MCP 工具
• MCP 服务源码实现 — 分层代理架构与 OpenAPI 服务注册核心逻辑
• 远程 MCP 服务源码 — 连通性测试、容器服务与端口管理
• OpenAPI 服务数据库层 — 以服务为单位的持久化与软删除实现

• 人工智能
• AI Agent
• Agent 编排
• 低代码
• AI 技能
• RAG