MCP 工具参数类型强制转换：为什么模型输出的字符串数字会让服务端校验失败
Agent 调用带数值与布尔参数的 MCP 工具时，模型常把 5 写成 "5"、把 true 写成 "true"，服务端按 inputSchema 严格校验就会直接拒绝。本文用一个库存查询工具贯穿全文，梳理类型声明、序列化路径、隐式转换歧义与枚举大小写问题，并对比客户端预校验与服务端宽松解析的取舍。
#MCP
共 21 篇文章
MCP 资源模板的 URI 展开：客户端拼出的路径为何在服务端解析失败
远程 MCP Server 用 RFC 6570 模板声明文件与数据库资源时，客户端填充变量、服务端匹配模板这两步经常对不上。文章拆解模板展开、百分号编码、路径段转义与匹配歧义，说明解析失败发生在哪一环，并给出校验点与可观测指标。
MCP 工具列表分页游标：为什么工具数量超过一页后客户端只看到部分工具
远程 MCP Server 注册的工具超过一页时，tools/list 会返回 nextCursor，客户端必须带着游标继续拉取才能拿到完整工具集。本文解释分页契约、客户端漏跟游标和服务端游标失效这两类故障，并给出校验点与可观测指标。
MCP 初始化能力协商：客户端未声明的能力为何让服务端功能静默失效
以远程 MCP Server 启动握手为场景，说明 initialize 请求中 capabilities 如何声明双方支持的采样、通知与根目录能力，分析客户端漏报 sampling 或 roots 后服务端调用被拒或降级的机制，并给出可观测指标与兼容性边界。
MCP 工具调用超时重试：客户端重发请求为何导致写操作重复执行
远程 MCP Server 执行下单类写工具时，客户端超时重发同一 JSON-RPC 请求，服务端却把它当成一次新调用，导致重复扣款或重复下单。本文从 JSON-RPC 请求 ID 的会话内语义出发，解释断线重连后 ID 重置、服务端缺少幂等键存储的机制，并对比幂等键、去重窗口与人工确认三种方案，给出可观测指标与部署边界。
MCP Streamable HTTP 的 SSE 保活与代理缓冲：工具调用响应为何被中间层攒住
远程 MCP Server 经反向代理暴露时，工具调用结果常在客户端迟迟不出现。本文以 nginx 反代场景为例，解释 SSE 流为何需要周期性保活事件、代理缓冲与空闲超时如何攒住响应、Content-Type 改写为何让客户端解析失败，并给出可观测指标与部署边界。
MCP 工具输出校验：structuredContent 与 outputSchema 不一致时客户端为何解析失败
远程 MCP Server 返回结构化工具结果时，outputSchema 声明返回结构，structuredContent 承载实际负载。本文用一个订单查询工具贯穿全文，分析二者不一致、schema 未声明、客户端只读 content 文本分支时各自的解析失败路径，对比纯文本封装与严格校验两种方案，并给出服务端与客户端的校验点和可观测指标。
MCP Ping 心跳与超时判定：长任务执行中连接为何被误判为断开
远程 MCP Server 执行长任务时，客户端常因 ping 超时误判连接断开并重复重连。本文围绕双向存活探测、请求超时与进度通知的区别，分析事件循环阻塞、SSE 流空闲和代理层超时如何制造假故障，并给出心跳间隔与可观测指标的配置思路。
MCP 日志级别通知：为什么服务端调高日志级别后客户端仍收不到调试日志
远程 MCP Server 排障时，服务端明明调高了日志级别，客户端却只看到 info 以上日志。文章从 logging/setLevel 与 notifications/message 的职责划分入手，解释级别未同步、通知未订阅、会话重连后级别重置三类日志缺失，并对比本地日志与轮询方案的取舍。
MCP Streamable HTTP 的 JSON 响应模式：服务端不返回 SSE 流时，工具结果为何会丢失
远程 MCP Server 返回单次工具结果时，服务端可以直接用 application/json 响应，而不必开启 SSE 流。这篇文章解释规范允许的两种响应形态、客户端对 Content-Type 的解析假设、请求与响应的配对方式，以及 JSON 单次响应与 SSE 流式响应在兼容性、可观测性和失败模式上的差异。
MCP 工具注解的信任边界：readOnlyHint 与 destructiveHint 为何不能作为安全依据
Agent 自动调用写操作工具时，客户端常靠 readOnlyHint、destructiveHint 决定是否弹窗确认。本文拆解这些注解的语义与来源，说明它们由服务端自述、客户端无从验证的信任假设，对比服务端强制鉴权与人工审批，并给出校验方法与可观测指标。
MCP Streamable HTTP 的会话绑定：为什么窃取 Mcp-Session-Id 就能冒充客户端
远程 MCP Server 暴露在公网时，Mcp-Session-Id 只负责关联一次有状态会话，并不自动证明请求者是谁。文章解释会话 ID 与会话状态如何建立、为何可预测或未与访问令牌绑定，以及重连后不重新校验如何导致会话劫持，并对比无状态模式与每请求鉴权，给出绑定与轮换的可观测指标。
MCP 远程服务器的 OAuth 令牌受众校验：为什么为 A 服务签发的令牌能调用 B 服务
多台远程 MCP Server 共用同一授权服务器时，为 A 服务签发的访问令牌常能直接调用 B 服务。本文解释 RFC 8707 资源指示器与 aud 绑定机制，分析授权服务器未按资源签发、客户端复用令牌、资源服务器漏校验 aud 三类成因，对比静态 API Key 与逐服务令牌方案，并给出校验逻辑与可观测指标。
MCP 进度通知与取消：长任务执行中客户端如何中断并回收服务端资源
远程 MCP Server 执行耗时数据导出时，客户端如何用进度令牌跟踪任务、用取消通知请求中止，以及服务端如何回收临时文件与数据库连接。文章分析令牌缺失、取消竞态和资源未清理三类失败模式，并对比超时轮询与幂等重试的适用边界。
MCP Roots 文件系统边界：客户端声明的根目录如何限制工具服务端访问范围
本地 MCP Server 读写项目文件时，客户端通过 roots/list 声明的根目录决定了服务端能碰哪些路径。文章拆解根目录替换、变更通知、路径规范化与符号链接绕过，并给出可观测指标与部署边界。
MCP Sampling 反向调用：工具服务端如何借用客户端的大模型生成摘要
远程 MCP Server 想在工具执行中生成摘要，却不愿自持 API Key，这时 sampling/createMessage 让服务端反向请求客户端模型补全。文章拆解请求参数、模型偏好映射、结果回传与拒绝路径，对比服务端自持密钥方案，并给出可观测指标与适用边界。
MCP Elicitation 中途索要参数：工具执行到一半如何安全地向人类追问
工具跑到一半才发现缺少必填参数，直接报错会让用户重来一遍。本文以订位工具为例，拆解 MCP elicitation/create 如何暂停调用、用受限 JSON Schema 收集结构化输入并恢复执行，分析 accept、decline、cancel 三条路径、schema 校验失败与超时处理、敏感字段为何必须走 URL 模式，并给出可观测指标与适用边界。
MCP 资源订阅与变更通知：客户端订阅后为何仍读到过期资源内容
远程 MCP Server 暴露文件与数据库资源时，客户端调用 resources/subscribe 后仍可能读到旧内容。文章拆解订阅、通知与缓存刷新的完整链路，分析订阅粒度粗、通知丢失、重连后订阅状态不同步等失效原因，并对比轮询与版本校验的取舍，给出可观测指标与部署边界。
MCP 工具列表变更通知：服务端热更新后客户端为何仍在调用已删除的工具
远程 MCP Server 热更新工具后，客户端仍调用已删除工具，问题往往出在 tools/list_changed 通知链路而非服务端。本文拆解通知、重新拉取与缓存刷新的完整流程，分析通知丢失、未订阅、会话重连三类失效路径，对比轮询与版本校验方案，并给出可观测指标与部署边界。
MCP Streamable HTTP 断线重连：工具调用结果为什么会丢
移动网络下远程 MCP Server 断线重连后，工具调用结果可能凭空消失。文章从会话 ID、SSE 事件 ID 与 Last-Event-ID 重放机制入手，说明恢复成立的前提、服务端事件缓冲的边界，以及无状态模式为何无法重放，并给出可观测指标与部署取舍。
MCP 工具定义注入如何挤占上下文：工具 schema 的 token 开销与按需加载机制
接入多个 MCP Server 的 Agent 为什么越接越笨？本文从工具名、描述与 JSON Schema 被序列化进系统提示并随每轮请求重复计费讲起，分析工具数量增长带来的上下文挤占与选择准确率下降，对比全量注入、检索式筛选与动态发现三种加载策略的延迟与可靠性权衡，并给出可观测指标与适用边界。