运行并检查 MCP 服务器：Agentic AI 开发调试实战

从干净启动开始：暴露潜在的契约问题

在构建 Agentic AI 服务时，一次「干净的启动」往往能够暴露出接口契约（contract）层面的隐藏问题。本节课（Stage 28 — Lesson 8）聚焦于一个核心实践环节：如何正确运行并检查一个基于 FastMCP 的开发服务器，确保工具、资源与提示词三者都被正确暴露。

具体操作上，需要在已激活的项目环境中运行 FastTICPDevInspectorServer.py，并保持终端持续开启。这一步看似简单，却是后续所有调试工作的前提——只有服务器稳定运行，才能通过 Inspector 工具逐项验证服务端对外提供的能力。

FastMCP 是基于 Model Context Protocol（MCP）的 Python 开发框架，由 Anthropic 主导设计，旨在为 AI Agent 提供标准化的工具调用、资源访问与提示词管理接口。「接口契约」（contract）在此语境下指服务端与调用方之间关于输入参数名称、类型、必填性以及返回值结构的明确约定——一旦任意一方偏离约定，调用就会静默失败或产生难以排查的类型错误。Inspector 工具是 MCP 生态提供的可视化调试面板，可以在不编写任何客户端代码的情况下，直接向运行中的开发服务器发起调用、查看响应和检查暴露的能力列表，是开发阶段验证服务行为的首选手段。

验证服务端暴露的三类能力

MCP（Model Context Protocol）类型的服务通常对外暴露三类核心资源：工具（tools）、资源（resources）与提示词（prompts）。课程强调要确认 STO 已正确暴露这三者，这是判断服务端是否按预期工作的第一道检查关卡。

完成基础暴露检查后，下一步是深入检视某个具体工具的接口定义。以「百分比变化」（percentage change）这类计算工具为例，需要逐一核对它所要求的输入项、输出字段以及对应的数据类型。接口契约的清晰度直接决定了调用方能否正确传参与解析返回结果。

在 MCP 架构中，「工具（tools）」对应可被 Agent 主动调用的函数，通常用于执行计算、查询外部 API 等有副作用或需要返回结果的操作；「资源（resources）」是只读的上下文数据源，例如文档片段、数据库记录或配置信息，Agent 在推理前会先检索这些内容以丰富上下文；「提示词（prompts）」则是预定义的模板，经变量填充后作为系统指令或用户消息传入大模型。三者职责分明：工具负责「做事」，资源负责「提供信息」，提示词负责「给出指令」。STO 即 Server-Tools-Objects 的缩写，是 MCP 服务端能力集合的统称，确认三者均已正确暴露是后续所有功能验证的基础前提。

用具体数据测试计算逻辑

理论检查之后，必须用真实数据来验证逻辑是否符合预期。课程给出了明确的测试用例：输入 80 和 92，验证结果是否正确反映出 15 个百分点的增幅（15-point row and increase）。这种带有明确预期值的测试方式，是验证计算类工具正确性的标准做法。

通过真实数值的往返调用，可以同时确认两件事：一是工具的核心计算逻辑无误，二是输入输出的字段映射与类型转换没有偏差。对于金融、数据分析类的 Agent 工具来说，这类数值一致性校验尤为关键。

验证失败路径：移除末值触发校验

一个健壮的服务，不仅要在正常输入下给出正确结果，更要在异常输入下优雅地拒绝。课程特别设计了一个「负向测试」：移除末值（end value），观察校验是否按预期失败。

这里有一个值得关注的细节——当校验失败时，会话（session）应当保持连接状态，而不是因为单次输入错误就断开整个连接。这体现了良好接口设计的容错能力：输入校验的失败应该是局部的、可恢复的，而非让整个服务崩溃。这种「校验失败但会话存活」的行为，是生产级 Agent 服务应有的稳定性表现。

「负向测试」（negative testing）是软件工程中专门验证系统在非法或边界输入下行为是否符合预期的测试策略，与验证正常路径的「正向测试」互为补充。对于 Agent 工具而言，负向测试尤为重要：如果缺失必填参数时服务直接抛出未捕获异常并断开连接，客户端 Agent 将无法区分「参数错误」与「服务崩溃」，导致重试逻辑混乱。MCP 规范要求工具层面的输入校验应返回结构化的错误响应（而非 transport 层断连），使 Agent 能够读取错误信息、调整参数后重试，而不必重建整个会话。「会话保持连接」这一行为本质上是对 HTTP 长连接或 WebSocket 会话的保护，是生产级服务容错设计的重要体现。

检查资源内容与渲染后的提示词

除了工具调用，还需要验证服务端提供的资源内容（resource content）是否正确。资源往往承载着 Agent 运行所需的上下文数据，其准确性直接影响下游推理质量。

话说回来，渲染后的提示词（rendered prompts）也需要逐一检查。提示词模板在填充变量后的最终形态，决定了大模型实际接收到的指令内容。最后，课程要求在日志（logs）中追踪上述两条路径——资源与提示词的调用轨迹，确保服务端行为可观测、可追溯。

小结

本节课通过运行与检查 MCP 开发服务器，串联起 Agentic AI 调试的关键环节：从服务启动、能力暴露，到接口契约核对、正负向测试，再到资源与提示词验证及日志追踪。这套流程体现了构建可靠 Agent 服务的工程化思维——不仅关注功能是否可用，更强调契约清晰、校验健全与行为可观测。按照课程安排，接下来将进入 Stage 28 的第 9 课。