8.1 MCP server

8.1 MCP server

本节摘要：MCP（Model Context Protocol）是 Agent 生态里「工具挂接」的主流协议——laya 可以作为 MCP server 运行（官方口径提供 mcp 扩展），把决策能力暴露成 Agent 工具架上的标准工具：Agent 的规划模型按需调用，一次调用就是一次 laya 决策。本节走三步：启动侧——装扩展、起 server、确认工具被客户端发现；工具侧——决策工具的 schema 长什么样（写法示意，以官方文档为准）：输入是 context 加问题（typed 三原语的题面），输出是答案加概率加置信；挂接侧——给一个 MCP 客户端配置 server 并跑通最小调用。随后讲工具面设计的两个原则：schema 即文档（Agent 的模型靠描述决定何时调用，描述写歪了工具就白挂）、决策工具与生成工具的分工（判断这一格给 laya，生成留给大模型——第 5.3 节降级建模思想在 Agent 工具架上的翻版）。

学习目标

• 启动 laya 的 MCP server 并确认工具可被客户端发现。
• 读懂决策工具的 schema 示意，说出输入输出各对应 SDK 的什么。
• 给 MCP 客户端完成最小挂接并验证一次决策调用。
• 按两条原则设计工具面：schema 即文档、判断与生成分工。

一、MCP 是什么席位

先对齐场景。MCP 解决的问题是：Agent（一个会规划的大模型）需要外部能力时，通过统一协议发现并调用工具——工具列表、每个工具的输入输出 schema、调用约定都标准化，Agent 换工具不换代码。laya 进这张工具架的意义：Agent 的规划模型不必「顺便」做判断——分类、路由、护栏这类封闭判断从生成上下文里拆出来，变成一次毫秒级（官方 README 口径 32.8 毫秒量级）的工具调用。

无 MCP 时                            有 MCP 时
┌────────────────────────┐          ┌──────────┐   工具发现/调用    ┌──────────────┐
│ Agent 大模型            │          │ Agent    │ ◀──MCP 协议────▶ │ laya MCP     │
│ 判断与生成混在提示词里    │          │ 规划模型  │                  │ server       │
│ 慢·贵·每次重写判断逻辑   │          │ 只管规划  │                  │ 决策工具      │
└────────────────────────┘          └──────────┘                  └──────────────┘
                                     判断成为标准工具：毫秒级·可微调·可监控
​

启动侧的写法示意（命令与配置以官方仓库 README 为准）：

# bash —— 安装 mcp 扩展并启动 server（写法示意）
python -m pip install "laya[mcp]"          # 官方 extras 之一（官方口径）
laya-mcp                                    # 启动方式以官方文档为准
# 预期：server 以 MCP 约定的传输方式就绪（stdio 或 HTTP 形态以官方文档为准），
# 并向客户端声明自己暴露的决策工具
​

二、工具 schema：决策工具长什么样

MCP 工具的核心是 schema：名字、描述、输入结构、输出结构。laya 决策工具的 schema 示意（以官方文档为准，此处讲结构）：

# laya_tool_schema.json —— 决策工具 schema 写法示意（以官方文档为准）
{
  "name": "laya_decide",
  "description": "对给定状态文本做带类型的封闭决策：分类(choice)、评分(score)、是非(noul)。返回首选答案、完整概率分布与置信度。适合语义判断类任务；不适合开放生成。",
  "input": {
    "context": "被判断的状态文本，例如工单原文",
    "questions": [
      {
        "id": "问题标识",
        "type": "choice | score | noul",
        "question": "问题文本",
        "options": "choice 时的选项表"
      }
    ]
  },
  "output": {
    "results": "每问题一项：answer(答案) + probabilities(分布) + confidence(置信)"
  }
}
​

把 schema 与第 3 章对齐着看：input 就是 predict 的输入面（context 加 questions），output 就是四字段返回——MCP 形态没有发明新接口，是把 SDK 能力按 MCP 约定重新声明。这意味着第 1.2 节的问题设计纪律原封不动地适用：选项互斥、覆盖完整、留兜底项；Agent 场景里选项表常由工具调用方（规划模型）动态填写，动态选项撞上第 6 章的预算与两段式问题时要接住。

description 字段值得单独强调——它是 schema 里最重要的部分。Agent 的规划模型读描述来决定「这个工具什么时候该被调用」：描述写成「做 AI 决策」就太泛（什么都想调），写成「对封闭选项做毫秒级语义分类与判断，不适合开放生成」就既有吸引力又有边界。最后一句「不适合开放生成」不是客套，是给模型的分流指引——把第 9 章选型逻辑浓缩进一行描述，工具才不会被人（模型）用错。

三、挂接：客户端侧的最小示例

客户端配置的写法示意（以所用 MCP 客户端的文档为准）：

# mcp_client_config.json —— 客户端侧挂接配置（写法示意，字段以客户端文档为准）
{
  "mcpServers": {
    "laya": {
      "command": "laya-mcp",
      "args": []
    }
  }
}
​

# mcp_min_call.py —— Agent 侧最小调用（伪代码示意，以 MCP 客户端库为准）
# session = mcp_client.connect()            # 连接后工具自动进入工具列表
# tools = session.list_tools()
# print([t.name for t in tools])            # 预期看到 laya_decide（名称以官方为准）

# result = session.call_tool("laya_decide", {
#     "context": "用户消息：你们的退款政策太苛刻了，我要投诉到消协。",
#     "questions": [{
#         "id": "escalate",
#         "type": "noul",
#         "question": "这条消息是否有升级投诉风险？",
#     }],
# })
# 预期返回（示意值）：answer=yes / no / 不知道 + 置信
# 门控：低置信时 Agent 应转人工流程而不是继续自动处理（第 7.3 节）
​

验证挂接的三步：工具能列出（发现通）；一次真实调用返回结构完整（调用通）；返回的置信与第 7 章的预期一致（语义通——拿一条已知高置信样本试试，别只验证「有返回」）。

四、工具面设计两原则

原则一：schema 即文档。 Agent 场景里没有「API 文档页」这种东西——规划模型看得到的只有工具名、描述与参数结构。三个落地动作：描述里写清「适合什么、不适合什么」（上面说过）；参数名与业务语义对齐（escalate_risk 比 flag2 直观，模型的调用准确率会说话，示意判断）；选项表若由调用方动态填，在描述里写明「options 须互斥且含兜底项」——把第 1.2 节的选项纪律 encode 进 schema，让模型当你的标注质检员之前先当个合格的出题人。

原则二：判断与生成分工。 工具架上 laya 与大模型各就各位：封闭判断（分类、路由、护栏、资格判断）给 laya——毫秒级、可微调、概率可信（校准后）；开放产出（写回复、做总结、多步规划）给大模型。判断错位的两个典型反例：让规划模型「顺便」判断消息是否违规（慢、贵、判断质量随提示词漂移）；让 laya 生成安抚话术（做不到，答案空间封闭是它的天性不是缺陷）。分工的判断标准回第 1.2 节速查表：「有限集合里挑一个」给 laya，「开放文本」给大模型——第 5.3 节 browser-agent 的分层设计（laya 决策头加大模型兜底）在工具架上的投影而已。

五、运维注脚

MCP 形态的运维要点三条。其一，server 与 laya-serve（第 4 章）可以共存也可以合并——按调用方画像决定：Agent 流量走 MCP、服务间流量走 HTTP，两套入口共享同一份检查点缓存与配置。其二，监控进 MCP 通道要另做一层：工具调用次数、被 Agent 采纳率（调了 laya 的判断后规划是否遵循）是这套形态特有的指标（示意建议）。其三，版本纪律不变：MCP 协议本身在演进，客户端与服务端的协议版本要对齐——升级 laya 前先看官方的兼容说明（第 3.1 节的「字段以实测版本为准」纪律平移过来）。

本节要点回顾

• laya 可作为 MCP server 运行（官方口径，mcp 扩展）；Agent 的规划模型按需调用决策工具。
• schema 与 SDK 同构：input 即 predict 输入面，output 即四字段返回；没有新接口，只有新声明。
• description 是 schema 的灵魂：写清适合与不适合，把选型逻辑浓缩给规划模型看。
• 分工原则：封闭判断给 laya，开放产出给大模型；判断标准回第 1.2 节速查表。
• 挂接验证三步：发现通、调用通、语义通；运维上与 serve 共存、另做采纳率监控、钉协议版本。

MCP 让 laya 坐上 Agent 的工具架。下一节换一条生态线：应用编排——LangChain 的链与 LangGraph 的图里，laya 怎么做路由节点与人工介入节点。