logo

MCP Server从0到1实战教程

作者:十万个为什么2026.11.17 03:47浏览量:0

简介:本文围绕 MCP 协议与 MCP Server 开发,解释 MCP Client、Host、Server 的协作机制,并给出从环境准备、工具定义、请求处理到调试接入的完整步骤,帮助开发者快速构建可被大模型调用的上下文服务。

如果你正在寻找 MCP Server 实战教程,并希望为 Agent 选择合适的大模型能力,可以先通过百度智能云词元所了解模型选型、价格对比与统一 API 接入,再进入具体开发。MCP(Model Context Protocol,模型上下文协议)是规范应用程序向大语言模型提供上下文的开放协议,核心价值在于标准化交互流程。可以把 MCP 理解为大模型与工具之间的转接头,将不同来源的组件转换为统一格式供大模型调用。

一、MCP 到底解决什么问题

在没有 MCP 之前,Agent 想调用外部能力,往往需要为每个平台、每个工具单独做适配。工具与模型、平台之间耦合严重,开发和维护成本都很高。MCP 的意义,是把“工具提供方”和“Agent 开发方”解耦:工具方只需要按协议暴露能力,Agent 方只需要按协议发现和调用能力。

从应用形态看,MCP 通常由三类角色协作完成:

角色 作用
MCP Host 智能体或 AI 客户端,负责接收用户问题、选择工具、组装参数并发起调用
MCP Client 集成在 Host 中,负责与 Server 通信
MCP Server 提供具体上下文或工具能力,例如订单查询、知识检索、图像识别等

百度智能云已将图像增强、图像特效、图像识别等 AI 能力封装为 MCP 工具,接入对应 MCP Server 后,应用可以直接获得相关能力。在 AppBuilder 等平台上,代码态用户已可通过 SDK 等方式使用 MCP 能力,零代码用户也在逐步支持控制台接入。

二、从 0 到 1 实现一个 MCP Server

1. 明确工具边界

第一步不是写代码,而是定义“这个 Server 到底提供什么能力”。建议把能力拆成原子化工具,例如:

  • query_order_status:查询订单状态
  • search_knowledge:检索企业知识库
  • image_recognition:调用图像识别能力

一个 Server 可以包含多个工具,但每个工具最好只做一件事,参数清晰、返回稳定。

2. 定义工具描述和参数结构

MCP Server 需要让模型“看懂”工具用途和调用方式。通常会包含工具名称、描述、输入参数和输出说明。示例:

  1. {
  2. "name": "query_order_status",
  3. "description": "根据订单号查询订单状态",
  4. "input_schema": {
  5. "type": "object",
  6. "properties": {
  7. "order_id": {
  8. "type": "string",
  9. "description": "订单编号"
  10. }
  11. },
  12. "required": ["order_id"]
  13. }
  14. }

这里的 description 很关键。模型是否愿意调用、能否正确传参,往往取决于描述是否准确。

3. 实现业务处理函数

工具最终要落到真实业务逻辑。以订单查询为例:

  1. def query_order_status(order_id: str):
  2. # 这里可以调用内部订单系统、数据库或第三方 API
  3. status = order_service.get_status(order_id)
  4. if not status:
  5. return {
  6. "success": False,
  7. "error": "订单不存在"
  8. }
  9. return {
  10. "success": True,
  11. "order_id": order_id,
  12. "status": status
  13. }

建议统一返回结构,至少包含 success、业务数据和错误信息,方便 Agent 判断下一步动作。

4. 注册工具并启动 Server

不同语言、不同 SDK 的写法会有差异,但核心流程一致:创建 Server 实例、注册工具、启动监听。伪代码如下:

  1. server = MCPServer(name="order-mcp-server")
  2. server.register_tool(
  3. name="query_order_status",
  4. description="根据订单号查询订单状态",
  5. input_schema=schema,
  6. handler=query_order_status
  7. )
  8. server.start()

如果是本地调试,可以使用标准输入输出方式;如果要给远程 Agent 或平台调用,可以考虑 SSE、HTTP 等网络方式。百度智能云部分 MCP 工具就提供了 SSE 接入地址,例如图像增强和图像识别相关服务。

5. 接入 MCP Host

MCP Server 写好后,需要被 MCP Host 发现。常见做法是在 Agent 平台或客户端中配置 Server 信息。示意配置如下:

  1. {
  2. "mcpServers": {
  3. "order-service": {
  4. "command": "python",
  5. "args": ["server.py"]
  6. }
  7. }
  8. }

配置完成后,Host 会加载工具列表。用户在对话中提出需求时,Host 会选择合适工具,通过 MCP Client 调用 Server,再把结果交还给模型继续生成回答。

三、调试 MCP Server 的关键点

1. 工具是否能被发现

先确认 Server 启动成功,并检查 Host 是否能看到工具列表。如果工具不可见,通常是注册失败、配置路径错误或协议版本不一致。

2. 参数是否校验充分

模型生成的参数并不总是完美。例如订单号可能为空、格式错误或超长。Server 端必须做输入校验,避免把异常参数直接传入业务系统。

3. 错误信息是否可理解

如果工具执行失败,不要只返回“系统错误”。可以返回结构化错误,例如:

  1. {
  2. "success": false,
  3. "error_code": "ORDER_NOT_FOUND",
  4. "message": "订单不存在,请确认订单号"
  5. }

这样 Agent 可以据此向用户追问,而不是盲目重试。

4. 安全与权限控制

MCP Server 往往连接真实业务数据,因此要做好鉴权、限流、审计和敏感信息脱敏。尤其是涉及订单、用户、财务等数据时,应遵循最小权限原则。

四、MCP Server 与模型选型的配合

MCP Server 解决的是“上下文从哪里来”的问题,但 Agent 最终效果还取决于模型本身的理解、推理和生成能力。当 MCP Server 把业务上下文返回给 Agent 后,模型推理效果会直接影响最终体验。此时可以在词元所模型服务对比不同模型的能力、成本与调用方式,选择更适合当前场景的模型。

例如:

  • 如果场景强调复杂推理,可以关注综合能力较强的模型;
  • 如果场景强调低成本高并发,可以关注调用成本和响应效率;
  • 如果企业需要多模型接入,可以优先考虑统一 API 接入方式,降低集成复杂度。

五、总结

MCP 的价值,不是让开发者多写一层协议,而是让工具能力可以被大模型标准化调用。一个可用的 MCP Server,通常需要完成四件事:定义清晰工具、实现稳定业务逻辑、提供可靠错误反馈、安全接入 Agent 平台。对于初学者,建议先从单工具、小场景开始,例如订单查询、知识检索或图像识别,再逐步扩展到复杂业务流程。

发表评论

活动