MCP 学习笔记

1. MCP 是什么？

MCP，全称 Model Context Protocol，即模型上下文协议。

一句话理解：

MCP 是一套标准协议，让 AI Agent 能够用统一的方式连接外部工具、数据源和业务系统。

举个例子，如果你做了一个电商客服 Agent，用户可能会问：

我的订单到哪了？
我要申请退款。
这个商品还有库存吗？
优惠券为什么不能用？
帮我查一下售后进度。

这些问题，光靠大模型自己是回答不了的。因为大模型并不知道用户的真实订单、物流、库存或退款状态。

因此，你需要让 Agent 连接这些外部系统：

订单系统
物流系统
库存系统
优惠券系统
退款系统
售后工单系统
用户会员系统

MCP 的作用就是：

让 AI Agent 通过统一的方式连接这些系统，并在需要时调用对应的工具。

---

2. 没有 MCP 会怎样？

没有 MCP 时，电商客服 Agent 通常需要为每个外部系统单独编写适配逻辑：

接订单系统 → 写一套接口
接物流系统 → 写一套接口
接退款系统 → 写一套接口
接库存系统 → 写一套接口
接优惠券系统 → 又写一套接口

这会带来一系列问题：

集成方式混乱，各自为政
不同 Agent 之间无法复用工具
工具说明不统一，容易用错
权限和安全难以集中控制
后期维护成本越来越高

引入 MCP 之后，我们可以把这些外部能力统一封装成一个个 MCP Server。例如：

order-mcp-server        → 负责订单查询
logistics-mcp-server    → 负责物流查询
refund-mcp-server       → 负责退款和售后
product-mcp-server      → 负责商品、库存、价格查询
coupon-mcp-server       → 负责优惠券查询与核销规则

电商客服 Agent 只需要对接这些 MCP Server，就可以自动发现并使用它们提供的工具。

---

3. MCP 的基本架构

MCP 采用典型的 Client-Server 架构。

在电商客服 Agent 场景中，可以这样理解整个调用链路：

用户
  ↓
电商客服 Agent
  ↓
MCP Client
  ↓
MCP Server
  ↓
订单系统 / 物流系统 / 库存系统 / 退款系统 / 优惠券系统

具体到一次对话流程：

用户问：
「我的订单 20260502001 到哪了？」

  ↓ 客服 Agent 判断：
这是物流查询问题。

  ↓ MCP Client 发现：
有一个 query_logistics 工具，可以用来查物流。

  ↓ Agent 调用：
query_logistics(order_id="20260502001")

  ↓ MCP Server 请求真实物流系统。

  ↓ 物流系统返回：
包裹已到达深圳转运中心，预计明天派送。

  ↓ Agent 组织语言，回复用户。

这里有一个关键点需要注意：

大模型本身并不直接访问数据库，也不会直接请求物流系统。真正执行动作的是 MCP Server。

---

4. MCP 中的三个核心概念

一个 MCP Server 通常可以暴露三类能力：

Tools     → 工具
Resources → 资源
Prompts   → 提示词模板

你可以这样记忆：

Tool     = 让 Agent 动手「做事」
Resource = 给 Agent 提供「资料」
Prompt   = 让 Agent 使用固定的「话术模板」或流程指引

对应到电商客服场景中：

类型	作用	电商客服示例
Tool	执行动作	查询订单、查物流、申请退款、创建售后工单
Resource	读取资料	退款规则、发货规则、会员权益说明
Prompt	复用模板	售后安抚话术、退款处理话术模板、投诉升级流程模板

---

5. Tools：工具

5.1 Tool 是什么？

Tool 就是 Agent 可以调用的函数。

在电商客服 Agent 中，你可以准备这样一批工具：

query_order                 → 查询订单详情
query_logistics             → 查询物流进度
query_refund_status         → 查询退款状态
apply_refund                → 发起退款申请
query_product_stock         → 查询商品库存
query_coupon_status         → 查询优惠券是否可用
create_after_sales_ticket   → 创建售后工单
transfer_to_human           → 转人工客服

工具，就是 Agent 的“手”。Agent 不只是回答问题，还可以通过这些工具去真实系统里查询数据或执行操作。

5.2 一个 MCP Tool 示例

下面是一个查询订单的简单示例：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("ecommerce-customer-service")


@mcp.tool()
def query_order(order_id: str) -> str:
    """
    查询订单基础信息。
    当用户询问订单状态、订单金额、购买商品、下单时间、是否支付时使用。
    不用于查询物流轨迹，物流问题应使用 query_logistics。

    参数：
    - order_id: 用户订单号
    """
    return f"""
订单号：{order_id}
订单状态：已发货
商品名称：无线蓝牙耳机
订单金额：199 元
下单时间：2026-05-01 14:30
支付状态：已支付
"""

这里的 @mcp.tool() 的作用就是：将一个普通的 Python 函数注册为 MCP 工具，让 AI Agent 可以在需要时调用它。

5.3 物流查询工具示例

@mcp.tool()
def query_logistics(order_id: str) -> str:
    """
    查询订单物流轨迹。
    当用户询问「快递到哪了」「物流进度」「什么时候送到」「包裹还没收到」时使用。
    不用于查询订单金额、商品信息或退款状态。

    参数：
    - order_id: 用户订单号
    """
    return f"""
订单号：{order_id}
快递公司：顺丰速运
运单号：SF1234567890
当前状态：运输中
最新轨迹：包裹已到达深圳转运中心
预计送达：2026-05-03
"""

当用户问：

我买的耳机怎么还没到？

Agent 会做出大致判断：

用户关心的是物流问题
需要拿到订单号
如果会话中已有订单号，就调用 query_logistics
如果没有，就先向用户追问订单号

5.4 退款状态查询工具示例

@mcp.tool()
def query_refund_status(order_id: str) -> str:
    """
    查询订单退款状态。
    当用户询问「退款到哪了」「钱什么时候退」「退款审核了吗」「售后进度」时使用。
    不用于发起新的退款申请。

    参数：
    - order_id: 用户订单号
    """
    return f"""
订单号：{order_id}
退款状态：银行处理中
退款金额：199 元
预计到账时间：1-3 个工作日
"""

用户问：

我这个订单退款怎么还没到账？

Agent 就可以调用：

query_refund_status(order_id="用户订单号")

---

6. Agent 是如何决定调用哪个 MCP Tool 的？

Agent 并不是“凭空”知道工具存在的。

每个 MCP 工具都会向 Agent 暴露以下信息：

工具名称
工具描述
参数结构
参数说明

比如 query_logistics 很可能暴露为类似这样的结构：

{
  "name": "query_logistics",
  "description": "查询订单物流轨迹。当用户询问快递到哪了、物流进度、什么时候送到、包裹还没收到时使用。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "用户订单号"
      }
    },
    "required": ["order_id"]
  }
}

所以，当用户问：

我的快递到哪了？

模型会根据语义进行判断：

「快递到哪了」 → 物流问题
可用工具中有 query_logistics，正好是查询物流的
query_logistics 需要 order_id
用户没给出订单号
因此，先追问：「请提供一下您的订单号，我帮您查询物流进度」

如果用户明确说：

帮我查一下订单 20260502001 的快递到哪了

模型就可以直接调用：

{
  "tool": "query_logistics",
  "arguments": {
    "order_id": "20260502001"
  }
}

---

7. 工具描述非常关键

MCP 工具能否被 Agent 正确调用，很大程度上取决于工具描述写得够不够清晰。

❌ 差的写法：

@mcp.tool()
def query(order_id: str) -> str:
    """查询信息"""

这个描述太模糊。Agent 完全不知道它是查订单、查物流、查退款，还是查售后，很容易用错。

✅ 好的写法：

@mcp.tool()
def query_order(order_id: str) -> str:
    """
    查询订单基础信息，包括商品名称、订单金额、下单时间、支付状态、订单状态。
    当用户询问订单本身的信息时使用。
    如果用户询问快递、配送、包裹位置，不要使用本工具，请使用 query_logistics。
    如果用户询问退款、售后，不要使用本工具，请使用 query_refund_status。
    """

再比如：

@mcp.tool()
def query_logistics(order_id: str) -> str:
    """
    查询订单物流轨迹，包括快递公司、运单号、当前位置、预计送达时间。
    当用户询问快递、物流、配送、包裹到哪了、什么时候送到时使用。
    不用于查询订单金额、退款状态或商品库存。
    """

有了清晰的描述，Agent 才更容易选对工具。

---

8. Resources：资源

8.1 Resource 是什么？

Resource 是供 Agent 读取的参考资料。

在电商客服场景中，Resource 非常适合放置这些内容：

退款规则
发货与配送规则
退换货政策
会员权益说明
优惠券使用规则
平台客服话术规范
投诉升级流程

Resource 和 Tool 的核心区别在于：

Tool     → 执行动作、查询数据
Resource → 只提供资料、不执行动作

示例：

@mcp.resource("policy://refund")
def refund_policy() -> str:
    """
    退款规则说明。
    """
    return """
退款规则：

1. 未发货订单可以申请全额退款。
2. 已发货订单需要等待用户拒收或退回商品后处理退款。
3. 已签收订单支持 7 天无理由退货，部分特殊商品除外。
4. 退款到账时间通常为 1-3 个工作日。
5. 如用户情绪激动，应先安抚，再解释流程。
"""

这里的 @mcp.resource("policy://refund") 表示：将 refund_policy() 返回的内容注册为一份 MCP 资源，资源地址为 policy://refund。

8.2 常见 Resource 示例

可以设计这样一组资源：

policy://refund      → 退款规则
policy://shipping    → 发货和配送规则
policy://coupon      → 优惠券使用规则
policy://vip         → 会员权益说明
script://apology     → 客服安抚话术
script://complaint   → 投诉处理流程
faq://common         → 常见问题 FAQ

再举个例子，优惠券规则：

@mcp.resource("policy://coupon")
def coupon_policy() -> str:
    """
    优惠券使用规则。
    """
    return """
优惠券使用规则：

1. 优惠券需在有效期内使用。
2. 满减券必须满足订单金额门槛。
3. 部分优惠券不能与其他活动叠加。
4. 已过期优惠券不能恢复。
5. 如果用户反映优惠券异常，应结合 query_coupon_status 工具进一步确认。
"""

当用户问：

为什么我的优惠券不能用？

Agent 既可以读取 policy://coupon 这份资料，又可以调用 query_coupon_status 工具查询具体状态，从而给出更准确的回答。

---

9. Prompts：提示词模板

Prompt 是 MCP Server 暴露给 Agent 的可复用任务模板。

电商客服场景中，常见的 Prompt 可以包括：

退款处理回复模板
物流延迟安抚模板
投诉升级模板
差评挽回模板
售后工单总结模板
人工转接模板

示例：

@mcp.prompt()
def refund_response_prompt(customer_message: str) -> str:
    """
    退款问题回复模板。
    """
    return f"""
你是电商平台客服，请根据以下用户问题生成专业、礼貌、安抚型回复。

用户问题：
{customer_message}

回复要求：
1. 先表达理解和歉意
2. 再说明退款当前处理状态
3. 解释预计到账时间
4. 如需用户提供订单号，要明确说明
5. 语气温和，不要推卸责任
"""

Prompt 的作用是让 Agent 按照固定的风格和流程去完成任务，从而让回复更稳定、更专业。

---

10. Tool、Resource、Prompt 的区别

类型	作用	电商客服示例
Tool	执行动作	查订单、查物流、申请退款、创建工单
Resource	读取资料	退款政策、优惠券规则、会员权益说明
Prompt	固定流程	退款回复模板、投诉处理模板、安抚话术模板

一个简单好记的口诀：

Tool     → 查真实数据 / 做真实动作
Resource → 给 Agent 看的知识资料
Prompt   → 让 Agent 按固定流程回复

---

11. 一个完整的电商客服 MCP Server 示例

下面是一个简化但完整的示例，方便你快速理解整体结构：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("ecommerce-customer-service")


@mcp.tool()
def query_order(order_id: str) -> str:
    """
    查询订单基础信息。
    当用户询问订单状态、订单金额、购买商品、下单时间、是否支付时使用。
    不用于查询物流轨迹、退款状态或售后进度。
    """
    return f"""
订单号：{order_id}
订单状态：已发货
商品名称：无线蓝牙耳机
订单金额：199 元
支付状态：已支付
下单时间：2026-05-01 14:30
"""


@mcp.tool()
def query_logistics(order_id: str) -> str:
    """
    查询订单物流轨迹。
    当用户询问快递、物流、配送、包裹到哪了、什么时候送到时使用。
    不用于查询订单金额、商品详情或退款状态。
    """
    return f"""
订单号：{order_id}
快递公司：顺丰速运
运单号：SF1234567890
当前状态：运输中
最新轨迹：包裹已到达深圳转运中心
预计送达：2026-05-03
"""


@mcp.tool()
def query_refund_status(order_id: str) -> str:
    """
    查询退款状态。
    当用户询问退款到账、退款审核、售后进度、钱什么时候退回时使用。
    不用于发起新的退款申请。
    """
    return f"""
订单号：{order_id}
退款状态：银行处理中
退款金额：199 元
预计到账时间：1-3 个工作日
"""


@mcp.tool()
def query_product_stock(product_id: str) -> str:
    """
    查询商品库存。
    当用户询问某个商品是否有货、还能不能购买、什么时候补货时使用。
    """
    return f"""
商品 ID：{product_id}
商品名称：无线蓝牙耳机
当前库存：128 件
销售状态：可购买
"""


@mcp.tool()
def transfer_to_human(reason: str) -> str:
    """
    转接人工客服。
    当用户要求人工客服，或问题涉及投诉、情绪激烈、系统无法处理、金额争议时使用。

    参数：
    - reason: 转人工原因
    """
    return f"已为用户转接人工客服。转接原因：{reason}"


@mcp.resource("policy://refund")
def refund_policy() -> str:
    """
    退款规则说明。
    """
    return """
退款规则：
1. 未发货订单可以申请全额退款。
2. 已发货订单需要等待拒收或退回商品后处理退款。
3. 已签收订单支持 7 天无理由退货，特殊商品除外。
4. 退款到账时间通常为 1-3 个工作日。
5. 用户情绪激动时，应先安抚，再解释流程。
"""


@mcp.resource("policy://shipping")
def shipping_policy() -> str:
    """
    发货和配送规则说明。
    """
    return """
发货和配送规则：
1. 普通商品通常在下单后 24 小时内发货。
2. 大促期间可能延迟 1-2 天。
3. 偏远地区配送时间可能延长。
4. 如果物流超过 72 小时无更新，应建议创建售后工单。
"""


@mcp.resource("policy://coupon")
def coupon_policy() -> str:
    """
    优惠券使用规则说明。
    """
    return """
优惠券规则：
1. 优惠券必须在有效期内使用。
2. 满减券需满足订单金额门槛。
3. 部分优惠券不能与其他活动叠加。
4. 已过期优惠券不能恢复。
5. 如用户反馈优惠券异常，应查询优惠券状态。
"""


if __name__ == "__main__":
    mcp.run()

---

12. 如何配置 MCP Server？

假设这个文件保存为：

D:/ecommerce-mcp/server.py

常见的 MCP 配置如下：

{
  "mcpServers": {
    "ecommerce-customer-service": {
      "command": "python",
      "args": [
        "D:/ecommerce-mcp/server.py"
      ]
    }
  }
}

如果你使用虚拟环境：

{
  "mcpServers": {
    "ecommerce-customer-service": {
      "command": "D:/ecommerce-mcp/.venv/Scripts/python.exe",
      "args": [
        "D:/ecommerce-mcp/server.py"
      ]
    }
  }
}

如果你使用 uv：

{
  "mcpServers": {
    "ecommerce-customer-service": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "D:/ecommerce-mcp",
        "python",
        "server.py"
      ]
    }
  }
}

配置完成后，Agent 客户端就可以发现并使用这些 MCP 工具了。

---

14. 如果信息不够，Agent 会主动追问

用户说：

帮我查一下快递

Agent 看到 query_logistics 需要 order_id，但用户并没有提供订单号。

这时候，它不会胡乱查询，而是会自然地追问：

请提供一下您的订单号，我帮您查询物流进度。

这正是工具参数 schema 的作用。参数描述得越清楚，Agent 就越知道什么时候可以直接调用，什么时候需要先向用户补充信息。

---

15. MCP 和普通 API 的区别

普通 API 是由程序员主动调用：

query_logistics(order_id)

MCP 则是由 Agent 根据用户意图自动决定是否调用：

用户：「我的快递到哪了？」
  ↓ Agent 判断：这是物流问题
  ↓ 选择工具：query_logistics
  ↓ MCP Client 调用 MCP Server
  ↓ MCP Server 请求真实物流系统
  ↓ 结果返回给 Agent，由 Agent 回复用户

两者的核心区别在于：

普通 API → 代码里写死调用哪一个接口
MCP      → Agent 根据工具描述和用户问题，自动选择调用哪一个工具

---

16. MCP 和 Function Calling 的区别

可以这样理解：

Function Calling → 模型在单轮对话中调用某个函数的一种「能力」
MCP              → 让 AI 应用连接外部工具与上下文的「协议标准」

Function Calling 更偏向：

这一轮对话里，我给模型几个函数，它会判断是否调用、调用哪一个。

MCP 更偏向：

我有一个可以长期运行的工具服务，里面包含了工具、资源和提示词。
任何支持 MCP 的 Agent，都可以直接连接并使用这个服务。

所以，MCP 更适合用来构建：

工具生态
跨客户端复用
标准化集成
外部系统连接
上下文管理

---

19. 设计 MCP 工具的最佳实践

19.1 工具职责要单一

不要设计这种“万能工具”：

@mcp.tool()
def customer_service_tool(user_message: str) -> str:
    """处理所有客服问题"""

这样 Agent 很难准确判断该在什么场景下使用，后期维护也会很困难。

更好的做法是按职责拆分：

query_order()
query_logistics()
query_refund_status()
query_coupon_status()
transfer_to_human()

19.2 工具命名要清晰

❌ 不推荐：

query
check
handle
process
do_task

✅ 推荐：

query_order
query_logistics
query_refund_status
apply_refund
query_product_stock
transfer_to_human

工具名最好让人一看就知道它是做什么的。

19.3 描述中要写清楚“何时使用”和“何时不用”

示例：

@mcp.tool()
def query_order(order_id: str) -> str:
    """
    查询订单基础信息，包括商品名称、订单金额、下单时间、支付状态。
    当用户询问订单本身的信息时使用。
    不用于查询物流轨迹，物流问题应使用 query_logistics。
    不用于查询退款状态，退款问题应使用 query_refund_status。
    """

有了这种“正向+反向”的使用说明，模型就不容易选错工具。

19.4 参数要明确

❌ 模糊的参数：

def query(data: str):
    ...

✅ 清晰的参数：

def query_logistics(order_id: str):
    ...

如果需要多个参数，也要一一说明清楚：

@mcp.tool()
def apply_refund(order_id: str, reason: str) -> str:
    """
    为指定订单发起退款申请。

    参数：
    - order_id: 订单号
    - reason: 退款原因，例如：不想要了、商品破损、发错货、长时间未发货
    """

19.5 高风险操作要谨慎设计

查询类工具风险较低：

query_order
query_logistics
query_refund_status

操作类工具风险较高：

apply_refund
cancel_order
modify_address
create_compensation_coupon
close_complaint_ticket

这类工具最好加上限制措施：

需要用户确认
需要权限校验
需要记录操作日志
不能让 Agent 自动执行高金额退款
不能随意发放补偿券

例如：

@mcp.tool()
def apply_refund(order_id: str, reason: str, user_confirmed: bool) -> str:
    """
    发起退款申请。
    只有在用户明确确认要退款时才可以调用。
    user_confirmed 必须为 true。
    """
    if not user_confirmed:
        return "无法发起退款：用户尚未明确确认。"

    return f"已为订单 {order_id} 发起退款申请，原因：{reason}"

---

20. 安全注意事项

电商客服 Agent 在使用 MCP 时，需要格外注意安全问题。

20.1 不要暴露敏感信息

以下信息不应该被直接返回给模型或用户：

用户完整手机号
身份证号
支付账号
银行卡号
内部风控标签
数据库密码
API Key
后台管理 Token

如果必须展示部分信息，要做好脱敏处理：

手机号：138****5678
邮箱：u***@example.com

20.2 不要让 Agent 随意执行危险操作

危险操作包括但不限于：

直接退款
修改收货地址
取消订单
发放优惠券
关闭投诉
修改用户会员等级
删除订单记录

这些操作应当做到：

需要用户明确确认
需要权限判断
记录操作日志
设置金额上限
必要时强制转人工

20.3 输入要严格校验

用户的输入本质上不可信。例如可能出现：

订单号格式异常
商品 ID 不存在
用户伪造他人订单号
恶意构造参数

因此，MCP 工具应该做好基础校验：

订单是否属于当前用户
订单号格式是否正确
退款是否符合规则
优惠券是否属于该用户

20.4 返回结果要结构化

❌ 不够好的返回：

查不到

✅ 更友好的返回：

{
  "status": "not_found",
  "message": "未查询到该订单",
  "suggestion": "请用户确认订单号是否正确，或引导用户查看订单列表"
}

结构化的返回，能让 Agent 更好地进行后续判断与回复。

---

21. 最核心总结

最后，记住几句话就够了：

MCP = AI Agent 连接外部工具和上下文的标准协议。

MCP Server = 提供工具、资源、提示词的服务。

MCP Client = 连接 MCP Server，并将能力交给模型使用的客户端。

Tool = Agent 可以调用的动作，比如查订单、查物流、查退款。

Resource = Agent 可以读取的资料，比如退款规则、优惠券规则、客服话术。

Prompt = Agent 可以复用的任务模板，比如投诉处理模板、售后回复模板。

模型根据工具名、描述和参数 schema 判断调用哪个工具。

MCP 的真正价值在于：让 AI 从“只能聊天”变成“可以处理真实业务流程”的 Agent。