10.2 MCP server：把交易能力交给智能体
10.2 MCP server：把交易能力交给智能体
本节摘要：MCP（Model Context Protocol）是智能体消费外部工具的通用协议；QuantDinger 内置 MCP server（官方 README 口径），把系统能力封装成智能体原生可调用的工具。本节先过一遍典型的工具面——查行情、跑回测、下 paper 单等（具体清单以官方文档为准），并按风险度给工具分层；然后给出挂接配置示例，把 server 接到你自己的智能体客户端；最后是安全边界三原则：工具走作用域 token、白名单默认收窄、高危工具要求显式确认——思想直接取自《Harness 工程：从零打造智能体运行环境》第 04 章《工具系统》。一句话定位：MCP server 让智能体"会说交易系统的语言"，而作用域 token 决定它"被允许说哪几句"。
学习目标
- 描述 MCP server 暴露的典型工具面与风险分层。
- 完成一次挂接配置，让智能体客户端连上 QuantDinger 的 MCP server。
- 用三原则守住工具层的安全边界。
一、MCP server 暴露什么工具
MCP 的价值在于协议层：支持 MCP 的智能体客户端发现工具、理解工具描述、按结构化参数调用——你不需要为每个智能体框架写一遍胶水代码。QuantDinger 内置 MCP server 暴露的工具以官方文档为准，典型形态按风险分层如下（工具名为示意，以官方文档为准）：
| 层 | 典型工具（示意） | 风险 | 建议作用域 |
|---|---|---|---|
| 只读层 | 行情查询、K 线获取、账户只读信息 | 低：不改任何状态 | 只读行情 token 即可 |
| 计算层 | 提交回测、查询回测状态、拉取报告 | 中：消耗算力 | 只 paper 及以上 |
| 动作层 | 下 paper 单、撤 paper 单 | 高：产生订单（虚拟） | 只 paper 及以上 |
| 实盘层 | 真实订单相关（如开放） | 极高：动真钱 | 可交易 token + 显式确认 |
这张表的重点是"建议作用域"一列：工具的风险分层要与 10.1 的 token 分级对齐——只读 token 只能看到只读层工具，低权限的调用者在工具发现阶段就看不到高危工具，而不是调用了才被拒。减少可见性比事后拒绝更安全：智能体不会被"看得见但用不了"的工具描述诱导出错误的任务规划。
顺着最后一句往下说：工具的描述文本本身就是安全面的一部分。智能体规划任务时读的是描述——描述写得含糊（比如"执行交易操作"），智能体就可能在一个只该查数据的步骤里选中它。给动作层及以上工具写描述时，值得刻意写清前置条件与后果（"提交后即产生订单，需确认"），这不是文案修饰，是给智能体的规划过程加护栏，与《Harness 工程》第 04 章《工具系统》里"工具描述是智能体的行为说明书"是同一个观点。
二、挂接配置
（配置形态示意；server 的启动方式、端点与认证字段以官方文档为准。）
// mcp_client_config.json —— 智能体客户端挂接 QuantDinger MCP server（示意） { "mcpServers": { "quantdinger": { "transport": "http", "endpoint": "https://你的域名/mcp", "auth": { "type": "bearer", "tokenEnv": "QD_AGENT_TOKEN_PAPER" }, "tools": { "allow": ["market.ticker", "market.klines", "backtest.run", "paper.order"], "deny": ["*"] } } } }
三个字段值得注意。tokenEnv：token 从环境变量读，呼应 10.1 的保管纪律。tools.allow：白名单显式列出，宁可后续逐个加，不要默认全放开——这是《Harness 工程》第 04 章《工具系统》的白名单思想的直接应用：工具暴露面是一个安全参数，应当被审计和评审，而不是随库默认。tools.deny 设为通配兜底：allow 之外一律拒绝，语义上"未列出即禁止"。
挂接完成后的验证顺序（每步都有预期）：
| 步骤 | 动作 | 预期 |
|---|---|---|
| 1 | 工具发现 | 只出现 allow 列表内的工具 |
| 2 | 行情查询 | 返回结构化数据，延迟正常 |
| 3 | 提交一个小回测 | 任务受理，状态可查询 |
| 4 | 下一张最小 paper 单 | paper 账户出现记录 |
| 5 | 用只读 token 重复发现 | 动作层工具不可见 |
第 5 步是关键的边界验证：换一把低权限钥匙，确认门真的变窄了。
三、安全边界三原则
工具层的安全设计浓缩为三原则：
- 原则一，工具走作用域 token：MCP 调用与网关调用共享同一套凭证体系，不存在"MCP 通道绕过作用域"的旁路；如有旁路，那是必须立即修复的缺陷。
- 原则二，白名单默认收窄：新工具上线不自动进入 allow 列表；每次扩列是一次显式决策，与 token 升级同级对待。
- 原则三，高危动作显式确认：动作层及以上的工具，在智能体侧配置执行前确认（客户端的审批门能力，或你自建的确认脚本），确认记录进审计——智能体可以准备好一切，扣扳机前留一个人工检查点。
第三原则的取舍说明：确认会降低自动化程度，这正是它的目的。研究类任务（查行情、跑回测）可以全自动；产生订单的任务，无论 paper 还是实盘，保留一个确认点，成本是几秒钟，收益是挡住"智能体理解偏差导致的意外订单"这一最常见事故形态。等调用记录积累出可信度，再按 10.1 的升级逻辑逐步放开——自动化程度也应该是挣来的。
确认点的落地要有最小记录格式，否则复盘时无账可查（示意字段）：
| 字段 | 记什么 | 复盘时的用途 |
|---|---|---|
| 时间 | 请求到达与批准时刻 | 与订单流、告警对时间线 |
| 工具与参数摘要 | 哪个工具、关键参数 | 还原智能体当时想做什么 |
| 批准人 | 谁点的允许 | 权责可归因 |
| 结果 | 执行成功或失败 | 统计确认后的失败率 |
最后两个字段的组合还有一层用途：如果确认后的执行经常失败（参数错、配额超限），说明智能体的提案质量不稳，此时该做的是收紧白名单或加强描述，而不是加倍依赖确认点去兜底——确认挡的是"不该做的事"，不该替"做不对的事"背锅。
四、观察：工具调用也是系统行为
MCP 工具调用进入系统后，它就是普通的负载与普通的订单来源，纳入既有的观察体系：
- 调用侧：网关的调用频次、错误率、token 归因（第 11 章指标）。
- 订单侧：MCP 来源的 paper 单同样出现在 7.1 的信号观察与对账流程里，来源字段可区分。
- 决策门：MCP 触发的订单与策略订单走同一道门（第 09 章），门的 choice 分布按来源分别统计。
最后一条常被问：智能体下的单要不要过决策门？要。门审视的是订单与语境的匹配，与订单的发起者是谁无关——发起者越自主，越需要下游有一道不信任但讲道理的审查。
五、一次完整的智能体会话走查
把工具面、确认点、观察体系串起来，走一个研究型任务的全程（示意走查）：任务是对 BTC 近一个月的波动做一次"查行情、跑回测、paper 验证一单"。
| 阶段 | 智能体动作 | 系统侧行为 | 你看到什么 |
|---|---|---|---|
| 1 查行情 | 调用 K 线工具取近一月数据 | 只读层工具，不改变任何状态 | 审计日志一条只读调用 |
| 2 分析 | 在自己的环境里计算波动特征 | 不触达平台 | 无 |
| 3 跑回测 | 提交回测任务并轮询状态 | 计算层消耗配额，任务进队列 | 任务受理与完成事件 |
| 4 提议下单 | 组装 paper 单参数，请求确认 | 动作层工具触发确认点 | 一条待确认请求 |
| 5 确认后执行 | 下 paper 单 | paper 账户记账，过第 09 章决策门 | 信号与 choice 记录 |
三个容易出岔的点。其一，第 2 步的"分析"要在智能体自己的环境里做，而不是想办法让平台代算——工具面是给动作的，不是给思考的；把思考也塞进工具调用，等于把智能体变成一台远程脚本执行器。其二，第 4 步的确认请求如果被你在客户端一路点"允许"，确认点就退化成鼠标惯性——隔一段时间回看自己的确认记录，数一数有多少条是认真看过的，这个比例就是确认机制的真实剩余价值。其三，第 5 步的 paper 单一样过决策门：智能体发起的订单没有豁免权，choice 分布按来源分别统计之后，它反而多了一层可观察的行为记录——出问题时，你能区分"策略疯了"还是"智能体理解偏了"。
六、常见问题与排查
| 问题 | 排查方向 | 要点 |
|---|---|---|
| 智能体看不到任何工具 | token 作用域与 allow 列表交集为空 | 先查作用域，再查白名单 |
| 调用报工具不存在 | 工具名对不上或未列入 allow | 工具名以官方文档为准，allow 逐个加 |
| 回测任务提交后被限流 | 租户或 token 级配额 | 属预期行为，错峰重试或申请调额 |
| 确认点太频繁想关掉 | 自动化程度要"挣来" | 先看确认拦截记录的质量再谈放开 |
| MCP 订单与策略订单分不清 | 来源字段 | 对账与决策门统计按来源分桶 |
第二行是接入期最高频的问题：allow 列表里的工具名是手写的，官方文档里改名或换版本后，白名单就悄悄失效了——症状恰好是"工具不存在"而不是"权限不足"，容易误导排查方向。对策是把挂接配置纳入第 11.2 节升级预检的检查项：每次升级后重跑一遍五步验证，工具发现这一步数一数数量对不对。
本节要点回顾
- 工具面分四层：只读、计算、动作、实盘；风险分层与 token 分级对齐，低权限者连工具都看不见。
- 挂接三要点：token 走环境变量、白名单显式列出、未列即禁止；五步验证里换低权限钥匙复查是关键。
- 三原则：工具无旁路、白名单默认收窄、高危动作显式确认；自动化程度是挣来的。
- MCP 订单与策略订单同权同责：同一道决策门、同一套对账与观察。
网关与工具把"请进来做事"的通道管好了，但通道设计得再好，也要假设某一天需要一键切断。下一节讲多重应急开关——停新单、撤单、平仓、断网熔断类开关（文档口径四重），谁在什么情况下按，以及为什么每月要真的按一次。