logo

MCP Server 从0到1实战:协议原理与开发全流程教程

作者:热心市民鹿先生2026.11.17 03:50浏览量:1

简介:MCP 本质上是 MCP Client 与 MCP Server 之间的通信协议,它把 Agent 开发与工具开发彻底解耦:你只需按标准暴露能力,任何支持 MCP 的宿主(Claude、Cursor、自研 Agent 平台)都能直接调用。本文从架构原理讲到可运行的代码,并覆盖调试与选型要点;如果你在动手前想先确定用哪个模型来驱动 Agent 的 Function Calling,可以先在[百度智能云词元所](https://cloud.baidu.com/product-s/token_exchange.html?from=article)对比各模型的能力与调用成本,再决定技术栈。

一、先厘清概念:MCP 到底解决了什么问题

MCP(Model Context Protocol,模型上下文协议)是由 Anthropic 提出的开放标准,目标是构建大模型与数据源之间的安全双向链接,解决工具实现风格不统一、难以跨模型共享的问题。一个形象的比喻是:MCP 是大模型应用生态里的 Type-C 接口,把各种来源不同的组件统一成一种格式交给模型。

在 MCP 出现之前,模型想调用邮箱、日历、聊天软件,必须为每个平台单独写一个插件,插件与平台强绑定,A 平台写的在 B 平台用不了。MCP 把这件事标准化了。

一句话结论:MCP 是 Client 与 Server 之间的通信协议,它实现的是「Agent 开发」与「工具开发」的解耦。

注意一个常见误解:模型本身并不”说”MCP。MCP 报文走的是 JSON-RPC 2.0,由 Host 负责把工具描述转成模型能理解的 function calling 参数,再把模型返回的调用意图翻译成 MCP 请求。

二、三大核心组件与一次完整调用链路

组件 职责
MCP Host 协议执行者:接收用户问题 → 选择工具 → 构建参数 → 通过 Client 调用 Server → 解析结果 → 继续对话
MCP Client 负责发送请求 / 接收响应,通常内嵌在 Host 中,对用户不可见
MCP Server 处理请求并返回上下文数据,是你要开发的部分

集成 MCP Client 的智能体执行平台,或模型厂商的 Agent / AI 客户端(如 Cherry Studio、各类云上智能体应用),都可以承担 Host 职能。

Server 对外暴露三类能力(Primitives),这是设计时的核心决策:

  • Tools :可被模型主动调用的函数,有副作用,如查订单、发邮件。
  • Resources :只读上下文数据,如文件内容、数据库记录,通常由应用侧决定何时读取。
  • Prompts :预置的提示词模板,由用户显式触发。

新手最常犯的错是把所有东西都写成 Tool。只读数据优先用 Resource,能显著降低模型误调用率。

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

1. 环境准备

  1. pip install "mcp[cli]"

2. 最小可用版本

  1. from mcp.server.fastmcp import FastMCP
  2. mcp = FastMCP("demo-server")
  3. @mcp.tool()
  4. def query_order(order_id: str) -> str:
  5. """根据订单号查询订单状态。order_id 为订单编号。"""
  6. # 这里替换为真实业务查询
  7. return f"订单 {order_id}:已发货,预计明日送达"
  8. @mcp.resource("orders://recent")
  9. def recent_orders() -> str:
  10. """返回最近 10 笔订单摘要。"""
  11. return "ORD-1001 已发货; ORD-1002 待付款"
  12. if __name__ == "__main__":
  13. mcp.run(transport="stdio")

三个细节决定成败:

  1. docstring 必须写清楚参数含义 。这段描述会原样进入模型的上下文,是模型判断”该不该调、怎么传参”的唯一依据。写得含糊,模型就会瞎传。
  2. 类型注解必须完整 。FastMCP 依据类型注解自动生成 JSON Schema,缺注解会导致参数校验失败。
  3. stdio 模式下严禁向 stdout 打印日志 。任何 print 都会污染 JSON-RPC 报文流,导致握手失败。请统一用 logging 输出到 stderr。

3. 传输方式选型

传输 适用场景 特点
stdio 本地单机,客户端拉起子进程 最简单,无网络开销,不能跨机器
SSE 远程服务,服务端单向推送 兼容性好,需维持长连接
Streamable HTTP 云原生、多客户端共享 支持无状态部署与水平扩容,推荐新项目使用

本地开发用 stdio 起步,一旦要多人共用或上线,直接切 Streamable HTTP。

4. 接入 Host 验证

以 Claude Desktop 为例,在配置文件中登记:

  1. {
  2. "mcpServers": {
  3. "demo": {
  4. "command": "python",
  5. "args": ["/abs/path/to/server.py"]
  6. }
  7. }
  8. }

路径务必写绝对路径,相对路径是最常见的启动失败原因。

四、调试与排错清单

  • 用 MCP Inspector 先跑一遍 。它能在浏览器里直接列出 Server 暴露的 Tools / Resources 并手动调用,把”协议层问题”和”模型决策问题”隔离开。
  • 握手失败 :检查 initialize 阶段的 capabilities 声明与 protocolVersion 是否匹配。
  • 工具调不起来 :先看模型是否真的选中了工具。如果模型压根不发起调用,问题在模型侧而非 Server 侧——这类场景对模型的指令遵循和结构化输出能力要求较高,可以在词元所的大模型 API 服务平台上对比不同模型在工具调用上的表现与价格,再确定用哪个模型作为 Host 的推理引擎。
  • 超时 :外部 HTTP 依赖一定要设超时并加降级返回,否则一个慢接口会拖垮整个 Agent 会话。
  • 权限 :Server 等于把一段可执行能力开放给了模型,务必做入参白名单校验、鉴权和最小权限控制,不要直接把数据库连接串暴露给模型生成的参数。

五、不必从零造轮子:现成的 MCP 生态

生产实践中,自研 Server 往往只该承担”你独有的业务逻辑”,通用能力直接接现成的更划算。

百度智能云已把多项 AI 开放能力封装为 MCP 工具:图像增强 Server 提供拉伸图像恢复、去摩尔纹、对比度与清晰度增强、去雾去噪、无损放大、文档矫正去手写等能力;图像特效 Server 提供黑白上色、人像动漫化、风格转换。图像识别方向则覆盖车辆检测、车型识别、菜品与地标识别、通用物体场景识别,以及基于视觉专家模型与多模态大模型的”看图识万物”通识问答。

在应用侧,千帆 AppBuilder 也全面支持 MCP 协议:代码态用户可通过 AppBuilder Python-SDK 把自有组件转为 MCP Server,或直接接入已支持 MCP 的工具组件;云端组件市场的组件则无需 MCP,在页面点选添加后发布即可。

六、落地建议

  1. 先梳理业务中有哪些”高频、只读、幂等”的能力,把它们做成 Resource 或只读 Tool,风险最低、收益最快。
  2. 写 Server 时把 docstring 当产品设计文档来写,模型调用准确率提升-most 明显。
  3. 工具数量控制在 20 个以内,按业务域拆成多个 Server,避免上下文膨胀导致选错工具。
  4. 上线前用 Inspector 做一轮全量回归,并保留调用日志用于后续成本与效果分析——工具调用轮次直接决定 Token 消耗,选型阶段就做好模型价格与调用管理的评估,比事后优化便宜得多。

发表评论

活动