使用 FastMCP 开发自定义 MCP 服务器并集成到 Nexent 智能体平台

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

【免费下载链接】nexent

Nexent 是一个开源智能体SDK和平台，能够将描述流程的自然语言转化为完整的多模态服务 —— 无需编排，无需复杂拖拉拽。基于 MCP 工具生态系统构建，Nexent 提供灵活的模型集成、可扩展的数据处理和强大的知识库管理。我们的目标很简单：将数据、模型和工具整合到一个智能中心中，让任何人都能轻松地将 Nexent 集成到项目中，使日常工作流程更智能、更互联。

项目地址：
https://gitcode.com/ModelEngine/nexent

点击查看 免费下载

本文以 Nexent 官方文档《Model Context Protocol (MCP)》为骨架，系统讲解 MCP 协议的核心能力、基于 FastMCP 的服务器开发方法、将 MCP 服务接入 Nexent 智能体的完整流程，并结合 Nexent 仓库源码（backend/services/remote_mcp_service.py、backend/mcp_service.py、backend/services/mcp_management_service.py 等）剖析连接校验、容器托管、OpenAPI 转换与市场上架审核的底层实现。读完本文，你将能够独立开发一个 MCP 服务器、在 Nexent 中完成注册与工具分配，并理解 Nexent 如何以标准协议统一调度外部工具。

MCP 是什么：AI 的"USB-C"

Model Context Protocol（模型上下文协议，简称 MCP）是连接 AI 与外部系统（数据、工具、工作流）的开放标准，常被形象地比喻为 AI 的 "USB-C"。它让主机（Host，例如 Claude Desktop、Nexent 这类智能体平台）能够按统一协议发现并调用 MCP 服务器暴露的工具与资源，从而避免为每一家外部服务编写定制化集成代码。

MCP 的核心能力

MCP 服务器可以向主机暴露三类标准化能力：

主机可以通过标准协议连接本地或远程的 MCP 服务器，并自动发现其能力（例如自动获取工具列表、参数 Schema），这正是"无需编写胶水代码即可扩展智能体"的基础。Nexent 本身就是这样一个 MCP 主机：它内置了本地 MCP 服务（见 backend/tool_collection/mcp/local_mcp_service.py，通过 FastMCP("local") 挂载 nl2agent 等平台原生工具），同时以动态代理层接入用户配置的远程 MCP 服务与 OpenAPI 转换服务，形成"本地服务层 + 远程代理层 + 外部 API 层"的分层代理架构（见 backend/mcp_service.py 顶部注释）。

语言支持

MCP 协议本身与语言无关，官方与社区提供了多语言 SDK：

• Python ⭐（推荐新手使用）
• TypeScript
• Java
• Go
• Rust
• 以及其他支持 MCP 协议的语言

推荐优先使用 Python，因为其语法简洁易学，拥有 FastMCP 等丰富框架支持，可以快速构建原型，且有数千个成熟的第三方库（requests、httpx、数据库驱动等）可直接复用。Nexent 后端的 MCP 客户端与服务端均基于 Python 的 fastmcp 库实现（见 backend/services/remote_mcp_service.py 的 from fastmcp import Client 与 fastmcp.client.transports 导入），与官方推荐一致。

快速开始：用 FastMCP 构建第一个 MCP 服务器

前置要求

安装 FastMCP：

pip install fastmcp

基础示例：字符串处理服务器

创建一个简单的字符串处理 MCP 服务器，保存为 mcp_server.py：

from fastmcp import FastMCP

# 创建MCP服务器实例
mcp = FastMCP(name="String MCP Server")

@mcp.tool(
name="calculate_string_length",
description="计算输入字符串的长度"
)
def calculate_string_length(text: str) -> int:
return len(text)

@mcp.tool(
name="to_uppercase",
description="将字符串转换为大写"
)
def to_uppercase(text: str) -> str:
return text.upper()

@mcp.tool(
name="to_lowercase",
description="将字符串转换为小写"
)
def to_lowercase(text: str) -> str:
return text.lower()

if __name__ == "__main__":
# 使用SSE协议启动服务
mcp.run(transport="sse", port=8000)

运行服务器

python mcp_server.py

启动成功后，服务地址为 http://127.0.0.1:8000/sse。该地址即 MCP 的 SSE（Server-Sent Events）传输端点，Nexent 在接入时会据此自动选择传输方式。

源码层面的佐证：Nexent 的后端连通性校验会根据 URL 后缀自动识别传输协议——以 /sse 结尾的 URL 使用 SSETransport，其余（如 /mcp 结尾或未指明）使用 StreamableHttpTransport（见 backend/services/remote_mcp_service.py）。因此开发服务器时保持端点后缀规范（SSE 用 /sse、Streamable HTTP 用 /mcp），可以让 Nexent 以最高效的方式完成握手与工具发现。

集成到 Nexent：三步接入自定义 MCP 服务

MCP 服务器运行后，即可将其连接到 Nexent 智能体。

步骤 1：启动 MCP 服务器

确保服务器正在运行，并记录其访问地址（例如 http://127.0.0.1:8000/sse）。

步骤 2：在 Nexent 中注册

⚠️ 注意：

• 服务器名称只能包含英文字母、数字、下划线（_）和连字符（-），不能包含空格等其他字符。这一约束与后端注册逻辑一致——add_mcp_service 在写入记录前会先检查名称唯一性，重复名称会抛出 MCPNameIllegal 异常（见 backend/services/remote_mcp_service.py）。
• 如果使用 Docker 容器部署 Nexent，且 MCP 服务器运行在宿主机上，需要将 127.0.0.1 替换为 host.docker.internal（例如 http://host.docker.internal:8000），因为容器内的 localhost 指向容器自身而非宿主机。

步骤 3：使用 MCP 工具

配置完成后，在创建或编辑智能体时，您可以在工具列表中找到并选择您添加的 MCP 工具。被选中工具的调用请求由 Nexent 的 MCP 代理层转发给远端服务器，LLM 即可通过自然语言驱动这些工具完成实际任务。

注册背后的源码链路：连通性校验与工具发现

"添加"按钮并非简单保存一条 URL，而是一次完整的 MCP 协议级握手 + 工具发现：

如果连接失败，Nexent 会通过 _format_mcp_connection_error 对异常链进行归类（见 backend/services/remote_mcp_service.py），把底层异常翻译为可读的失败原因：连接超时（timeout）、连接被拒绝（connection refused）、认证失败（401/403）、端点不存在（404）、协议或端点不合法（invalid sse）、地址不可达（DNS 解析失败）等，便于快速定位问题。

平台级配额与环境变量

从 backend/consts/const.py 可以看到，Nexent 的 MCP 模块还暴露了以下可调参数（均通过环境变量注入）：

这些参数在部署 Nexent 时可按需调整，例如在内网环境可将超时时间适当调大以容忍较慢的服务。

高级用例：包装 REST API 与内部服务

包装 REST API

将现有的 REST API 包装为 MCP 工具，让智能体通过自然语言即可调用 HTTP 接口：

from fastmcp import FastMCP
import requests

mcp = FastMCP("Course Statistics Server")

@mcp.tool(
name="get_course_statistics",
description="根据课程号获取某门课程的成绩统计信息（包含平均分、最高分、最低分等）"
)
def get_course_statistics(course_id: str) -> str:
api_url = "https://your-school-api.com/api/courses/statistics"
response = requests.get(api_url, params={"course_id": course_id})

if response.status_code == 200:
data = response.json()
stats = data.get("statistics", {})
return f"课程 {course_id} 成绩统计：\\n平均分: {stats.get('average', 'N/A')}\\n最高分: {stats.get('max', 'N/A')}\\n最低分: {stats.get('min', 'N/A')}\\n总人数: {stats.get('total_students', 'N/A')}"
return f"API调用失败: {response.status_code}"

if __name__ == "__main__":
mcp.run(transport="sse", port=8000)

包装内部服务

如果成绩统计逻辑已经存在于内部 Python 模块中，可以直接在工具函数内调用，避免重复造 HTTP 层：

from fastmcp import FastMCP
from your_school_module import query_course_statistics

mcp = FastMCP("Course Statistics Server")

@mcp.tool(
name="get_course_statistics",
description="根据课程号获取某门课程的成绩统计信息（包含平均分、最高分、最低分等）"
)
def get_course_statistics(course_id: str) -> str:
try:
stats = query_course_statistics(course_id)
return f"课程 {course_id} 成绩统计：\\n平均分: {stats.get('average', 'N/A')}\\n最高分: {stats.get('max', 'N/A')}\\n最低分: {stats.get('min', 'N/A')}\\n总人数: {stats.get('total_students', 'N/A')}"
except Exception as e:
return f"查询成绩统计时出错: {str(e)}"

if __name__ == "__main__":
mcp.run(transport="sse", port=8000)

两个示例都体现了 MCP 工具的核心约束：函数签名即工具契约。FastMCP 会根据函数名、docstring 与类型注解自动生成工具 Schema，因此清晰的命名、描述与类型标注会直接决定 LLM 能否正确调用工具。

进阶：Nexent 的"API 转 MCP"免代码方案

如果你不想手写任何 MCP 服务器代码，Nexent 还内置了 API 转 MCP 能力：粘贴 OpenAPI 3.x 规范的 JSON，平台即通过 FastMCP.from_openapi() 批量加载该规范定义的所有 REST 接口，将其注册为 MCP 工具（见 backend/mcp_service.py 与 backend/services/tool_configuration_service.py）。转换后，智能体可以直接用自然语言调用这些 HTTP 接口，例如"查询所有待处理的工单"。该方案的详细操作（远程链接、容器化部署、API 转 MCP 三种接入方式及配置项表格）可参考 MCP 服务接入指南。

在 Nexent 中管理 MCP 服务：仓库、审核与容器托管

容器化 MCP 服务托管

除了直连远程 MCP 服务器，Nexent 还支持将 MCP 服务以容器方式托管运行。用户在配置中提交 mcpServers JSON（例如 command: "npx"、args: ["-y", "…" ]），Nexent 通过 MCPContainerManager 启动容器，并用 python -m mcp_proxy 作为内部代理把容器内 MCP 服务暴露为 Streamable HTTP 端点（见 backend/services/remote_mcp_service.py）。容器启动后还会执行最多 10 次、间隔 0.5 秒的健康检查，确保服务真正就绪才置为启用状态（见 backend/services/remote_mcp_service.py）。容器运行时支持 Docker 与 Kubernetes 两种后端，通过 IS_DEPLOYED_BY_KUBERNETES 自动切换（见 backend/services/mcp_container_service.py）。

MCP 仓库：同租户共享与上架审核

接入的 MCP 服务可以通过"MCP 仓库"在同租户内共享、管理与审核（详见 MCP 仓库使用指南）：

• 仓库页签：浏览租户中已上架（共享）的 MCP 服务，按名称或标签搜索，一键安装；
• 我的 MCP：管理自己有权限编辑的服务，支持启用/禁用、连通性校验、申请上架、查看审核进度、删除（容器化服务删除时会同步清理容器资源）；
• 审核中心（仅管理员可见）：处理上架申请，支持通过/驳回并填写审核意见。

其上架流程在源码中以状态机形式实现（见 backend/services/mcp_management_service.py）：MCP 记录在 not_shared（未共享）、pending_review（待审核）、shared（已共享）、rejected（审核驳回）四种状态之间迁移，且不同角色（SU、ADMIN、DEV）拥有不同的合法迁移集合，非法迁移会直接抛出异常（见 backend/services/mcp_management_service.py）。审核通过后，源 MCP 记录会与市场记录建立关联，服务即对租户成员可见（见 backend/services/mcp_management_service.py）。

最佳实践

• 日志记录：使用 stdio 传输时避免向 stdout 打印日志（不要 print），否则会污染 MCP 的 stdio 通信通道，日志应写入 stderr 或文件。
• 文档规范：工具的 docstring 与类型注解要清晰完整，FastMCP 会据此生成工具 Schema，直接影响 LLM 对工具的识别与参数生成质量。
• 错误处理：在工具内部友好地处理异常，向 LLM 返回可读的文本结果（如"查询成绩统计时出错: …"），而不是抛出堆栈信息，便于智能体据此调整策略或向用户转述。
• 安全性：敏感信息（API Key、Token、数据库口令）放入环境变量或密钥管理系统，严禁硬编码在代码或配置文件中。在 Nexent 侧注册远程服务时，也建议使用 Authorization Token 与自定义请求头进行鉴权，并将 Token 交由平台的密钥管理能力保管（见 MCP 服务接入指南 的安全建议）。

相关资源

Nexent 仓库内与本文主题直接相关的文档与源码，供继续深入：

• Nexent 智能体开发指南 —— 在智能体中配置与分配 MCP 工具
• MCP 服务接入指南 —— 远程链接、容器化部署、API 转 MCP 三种接入方式
• MCP 仓库使用指南 —— 浏览、安装、共享与审核 MCP 服务
• MCP 工具生态系统概览 —— MCP 协议在 Nexent 生态中的定位与优势
• MCP 推荐 —— 精选 MCP 平台与工具
• MCP 后端服务实现 —— 远程 MCP 注册、校验、启停与删除
• MCP 服务器本体 —— 本地服务层、租户级 SSE 路由与 OpenAPI 转换
• MCP 容器管理 —— Docker/Kubernetes 容器托管实现
• MCP 市场上架审核 —— 共享状态机与审核通知
• 常见问题 —— 部署与使用中的常见问题解答

赞

分享

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

【免费下载链接】nexent

Nexent 是一个开源智能体SDK和平台，能够将描述流程的自然语言转化为完整的多模态服务 —— 无需编排，无需复杂拖拉拽。基于 MCP 工具生态系统构建，Nexent 提供灵活的模型集成、可扩展的数据处理和强大的知识库管理。我们的目标很简单：将数据、模型和工具整合到一个智能中心中，让任何人都能轻松地将 Nexent 集成到项目中，使日常工作流程更智能、更互联。

项目地址：
https://gitcode.com/ModelEngine/nexent

点击查看 免费下载

相关推荐

• Nexent 平台 MCP 工具开发与接入实战：从 FastMCP 服务到 Agent 工具挂载

  Nexent 平台 MCP 工具开发与接入实战：从 FastMCP 服务到 Agent 工具挂载 本文以 Nexent 零代码 AI Agent 平台为背景，系

  AI Agent
  AI 应用
  后端
  前端
  大模型
  RAG

• Nexent 平台 MCP 工具开发与集成实战：基于 FastMCP 从零构建到 Agent 挂载

  Nexent 平台 MCP 工具开发与集成实战：基于 FastMCP 从零构建到 Agent 挂载 本篇指南以 Nexent 的 MCP（Model Conte

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

• 如何使用MetaMCP：重新定义MCP服务器管理的智能平台

  如何使用MetaMCP：重新定义MCP服务器管理的智能平台 MetaMCP是一个功能强大的MCP代理，让您能够动态地将MCP服务器聚合到统一的MCP服务器中，并

  后端
  API网关
  LLM 网关
  人工智能
  前端

上一篇：
终极边缘AI部署方案：Qwen3-VL-4B-Instruct-FP8完全指南

下一篇：
如何快速部署ZPan：构建私有云盘的完整指南

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考