Hermes Agent 接入 MCP 工具：从 dashboard 查询到 agent-toolkit 验证全流程

1. 为什么要在 Hermes Agent 上接入 MCP 工具

Hermes Agent 本身是一个任务编排与执行框架，它擅长把复杂流程拆成可调度的步骤，但默认能力集是有限的。当业务需要访问外部数据源、调用第三方服务、或者执行一些框架本身不内置的操作时，就需要一个标准化的扩展机制。MCP（Model Context Protocol）正是为此设计的——它定义了一套工具描述与调用的协议，让 Agent 能够以统一的方式发现、理解和调用外部工具。

我最初接触这个组合，是因为一个实际需求：团队内部有一个 dashboard 系统，用来展示各类任务的运行状态和指标。每次排查问题都要手动登录 dashboard 翻看数据，效率很低。如果能把这个 dashboard 的能力封装成 MCP 工具，让 Hermes Agent 直接调用，就可以在对话或自动化流程中实时获取状态信息，省去大量重复操作。

这个项目的核心目标很明确：把 dashboard 的查询能力通过 MCP 协议暴露出来，然后在 Hermes Agent 中注册这些工具，最后通过 agent-toolkit 完成调用验证。整条链路涉及三个关键环节——MCP 服务端的工具定义、Hermes Agent 的工具注册、以及 agent-toolkit 的调用测试。每个环节都有各自的坑，下面逐一拆解。

适合阅读这篇内容的读者包括：正在使用 Hermes Agent 做任务编排的开发者、需要给 Agent 扩展外部工具能力的工程师、以及对 MCP 协议感兴趣但还没实际落地过的技术同学。即使你之前没接触过 MCP，跟着思路走也能理解整个集成过程。

提示：MCP 的核心价值在于标准化。它不关心工具背后是什么实现，只关心工具的描述和输入输出格式是否规范。这种解耦设计让 Agent 的工具扩展变得非常灵活。

2. MCP 工具定义：从 dashboard 接口到协议描述

2.1 dashboard 现有接口的梳理与取舍

在动手写 MCP 工具之前，第一步是把 dashboard 现有的接口能力摸清楚。大多数 dashboard 系统都会提供若干查询接口，比如获取任务列表、查询单个任务详情、拉取指标数据、获取告警信息等。这些接口的返回格式通常是 JSON，字段结构也比较固定。

但并不是所有接口都适合封装成 MCP 工具。我的筛选原则有三条：第一，这个操作是否会被 Agent 频繁调用；第二，输入参数是否足够简单，不需要复杂的上下文；第三，返回结果是否适合直接嵌入对话或自动化流程。按照这三条标准，我最终选了四个接口作为第一批 MCP 工具：任务状态查询、指标数据拉取、告警列表获取、以及任务执行日志摘要。

这里有个容易忽略的点：dashboard 的接口可能有分页、鉴权、限流等机制。分页参数如果直接暴露给 Agent，会让工具描述变得复杂；鉴权 token 如果硬编码在工具里，又存在安全风险。我的做法是在 MCP 服务端做一层封装，把分页逻辑内部消化，默认返回最近 N 条记录，同时通过环境变量注入鉴权信息，工具描述里只保留业务相关的参数。

2.2 MCP 工具描述文件的结构与字段含义

MCP 工具的定义通常是一个 JSON 或 YAML 文件，核心字段包括工具名称、描述、输入参数 schema、以及输出格式说明。工具名称要简洁且语义明确，比如query_task_status就比get_task更清晰。描述字段非常关键，它是 Agent 理解工具用途的唯一依据，必须用自然语言写清楚这个工具做什么、什么时候用、返回什么。

输入参数的 schema 遵循 JSON Schema 规范，每个参数需要标注类型、是否必填、以及描述。这里有个经验：参数描述要写得足够具体，比如task_id的描述不要只写"任务 ID"，而要写"任务的唯一标识符，通常是一串 32 位字符串"。Agent 在调用时会根据这些描述来构造参数，描述越清晰，调用准确率越高。

输出格式虽然 MCP 协议没有强制要求，但我建议在工具描述里补充说明返回值的结构。比如"返回一个对象，包含 status 字段（字符串，取值 running/success/failed）和 metrics 字段（对象，包含 cpu、memory 两个数值）"。这样 Agent 在拿到结果后能更好地理解和呈现。

{ "name": "query_task_status", "description": "查询指定任务的当前运行状态和基础指标。适用于需要了解任务是否完成、是否异常的场景。", "inputSchema": { "type": "object", "properties": { "task_id": { "type": "string", "description": "任务的唯一标识符，32 位十六进制字符串" } }, "required": ["task_id"] } }

2.3 参数校验与错误返回的约定

MCP 工具在接收到调用请求后，第一件事应该是校验参数。如果task_id格式不对，或者必填参数缺失，要立即返回明确的错误信息，而不是让请求继续往下走。错误信息也要遵循一定的格式，方便 Agent 识别和处理。

我采用的错误返回结构是：{ "error": true, "code": "INVALID_PARAM", "message": "task_id 格式不正确，应为 32 位十六进制字符串" }。code 字段用大写下划线命名，message 字段用自然语言描述具体问题。这样 Agent 在收到错误后，可以决定是重试、提示用户、还是走其他分支。

还有一个细节：dashboard 接口本身可能返回各种错误码，比如 404 表示任务不存在、500 表示服务端异常。MCP 服务端需要把这些错误码转换成统一的错误结构，不要让原始错误直接透传。这样做的好处是 Agent 只需要理解一套错误约定，不用关心底层接口的差异。

注意：错误信息里不要暴露内部实现细节，比如数据库连接字符串、内部 IP 地址等。安全边界要在 MCP 服务端这一层守住。

3. Hermes Agent 侧的工具注册与配置

3.1 Agent 配置文件中 MCP 服务端的声明方式

Hermes Agent 要调用 MCP 工具，首先需要在配置文件里声明 MCP 服务端的地址和连接方式。通常有两种模式：一种是本地进程模式，Agent 直接启动 MCP 服务端进程并通过标准输入输出通信；另一种是远程模式，MCP 服务端作为一个独立服务运行，Agent 通过网络连接。

我选的是本地进程模式，因为 dashboard 的查询逻辑本身不重，没必要单独部署一个服务。配置大概长这样：

mcp_servers: - name: dashboard_tools command: python args: - /path/to/mcp_server.py env: DASHBOARD_TOKEN: ${DASHBOARD_TOKEN} DASHBOARD_BASE_URL: https://internal-dashboard.example.com

这里的关键点是环境变量的注入。鉴权 token 和基础 URL 通过环境变量传入，不写在配置文件里，避免泄露。command和args指定了启动 MCP 服务端的命令，Agent 会在需要时自动拉起这个进程。

3.2 工具发现机制与注册时机

Hermes Agent 启动时，会读取配置文件中的 MCP 服务端列表，然后依次连接每个服务端，调用其工具发现接口，获取该服务端提供的所有工具列表。这个过程是自动的，不需要手动逐个注册工具。

但这里有个时机问题：如果 MCP 服务端启动失败，或者工具发现接口返回异常，Agent 是直接报错退出，还是跳过这个服务端继续启动？我的建议是配置成"跳过并记录警告"，因为某个工具服务不可用不应该阻塞整个 Agent 的启动。Hermes Agent 通常支持这种容错配置，具体参数名可能是fail_on_mcp_error之类的，设成 false 即可。

工具发现完成后，Agent 会把所有工具的名称、描述、参数 schema 整合到自己的工具注册表中。之后在对话或任务执行过程中，Agent 就可以根据用户意图或任务需求，从注册表里选择合适的工具来调用。

3.3 工具调用时的参数传递与上下文注入

当 Agent 决定调用某个 MCP 工具时，它会根据工具的参数 schema 和当前上下文，构造出调用参数。这里有个值得注意的点：Agent 可能会从对话历史或任务上下文中提取参数值，比如用户说"查一下任务 abc123 的状态"，Agent 就会把abc123作为task_id参数传给query_task_status工具。

但 Agent 的提取不一定总是准确。为了提高成功率，可以在工具描述里补充一些示例，比如"例如：query_task_status(task_id='a1b2c3d4e5f6...')"。另外，如果某个参数经常从上下文获取，可以在 Agent 的提示词或配置里加一些引导，告诉它优先从哪些字段提取。

参数传递过程中还有一个安全考虑：不要让 Agent 有机会传入恶意参数。虽然 MCP 服务端会做校验，但在 Agent 侧也可以加一层白名单或格式检查，双重保险。

4. agent-toolkit 调用验证的完整链路

4.1 agent-toolkit 的安装与初始化

agent-toolkit 是一个用于测试和调试 Agent 工具调用的工具集，它可以模拟 Agent 发起工具调用，并展示完整的请求和响应过程。安装通常通过包管理器完成，比如pip install agent-toolkit或npm install -g agent-toolkit，具体取决于你的技术栈。

初始化时，需要指定 Hermes Agent 的配置文件路径，这样 agent-toolkit 才能读取到 MCP 服务端的配置信息。命令大概是agent-toolkit init --config /path/to/hermes_config.yaml。初始化完成后，agent-toolkit 会生成一个本地的工作目录，里面包含工具列表缓存和调用日志。

这里有个小坑：agent-toolkit 默认可能不会自动刷新工具列表，如果 MCP 服务端的工具定义有更新，需要手动执行agent-toolkit refresh来重新拉取。我在第一次使用时就是因为没刷新，导致新加的工具一直找不到。

4.2 逐个工具的调用测试与结果核对

工具列表就绪后，就可以逐个测试了。agent-toolkit 通常提供两种测试方式：交互式命令行和脚本化测试。交互式方式适合手动探索，输入工具名称和参数后，它会展示完整的调用链路和返回结果。脚本化方式适合批量验证，可以写一个测试脚本，把所有工具都跑一遍。

我以query_task_status为例说明测试过程。在 agent-toolkit 的交互界面里输入工具名称和参数task_id=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6，然后观察输出。正常情况下，应该能看到 MCP 服务端收到的请求、dashboard 接口的调用记录、以及最终返回的状态数据。

核对结果时要注意几点：返回的字段是否完整、数值是否合理、错误处理是否符合预期。比如故意传一个不存在的 task_id，看是否返回了正确的错误信息。再比如传一个格式错误的 task_id，看参数校验是否生效。

4.3 调用日志的解读与问题定位

agent-toolkit 会记录每次调用的完整日志，包括请求参数、MCP 服务端的处理过程、dashboard 接口的请求响应、以及最终返回给 Agent 的结果。当测试不通过时，日志是定位问题的第一手资料。

我遇到过一个典型问题：工具调用返回超时。查看日志后发现，MCP 服务端在调用 dashboard 接口时没有设置超时时间，dashboard 响应慢的时候就会一直等。解决方案是在 MCP 服务端的 HTTP 客户端里加上超时配置，比如 5 秒。这个问题在正常测试时不容易发现，只有在 dashboard 负载高的时候才会暴露。

另一个常见问题是参数传递错误。日志里会显示 Agent 实际传了什么参数，有时候会发现 Agent 把参数名拼错了，或者把数值型参数传成了字符串。这类问题通常通过优化工具描述和参数 schema 来解决。

提示：agent-toolkit 的日志默认可能只保留最近若干条，如果要做长期分析，建议配置日志轮转或导出到外部存储。

5. 联调中遇到的典型问题与排查思路

5.1 MCP 服务端启动失败：从进程日志找线索

MCP 服务端启动失败是最常见的问题之一。表现是 Hermes Agent 启动时提示某个 MCP 服务端连接不上，或者工具列表为空。这时候第一步是手动运行 MCP 服务端的启动命令，看它是否能正常启动。

我遇到过一次启动失败，原因是 Python 依赖缺失。MCP 服务端用到了一个 HTTP 客户端库，但环境里没装。手动运行时报了ModuleNotFoundError，装上依赖后就正常了。还有一次是环境变量没传进去，导致服务端启动时读取配置失败。这类问题通过手动运行命令基本都能快速定位。

如果手动运行没问题，但 Agent 启动时还是失败，那就要检查 Agent 的配置文件了。常见错误包括：命令路径写错、参数格式不对、环境变量名拼错等。Agent 的日志里通常会有更详细的错误信息，仔细看一遍基本能找到原因。

5.2 工具调用返回空结果：参数与接口的双向核对

工具调用返回空结果，但也没有报错，这种情况比较隐蔽。可能的原因有两个：一是参数传错了，导致 dashboard 接口查不到数据；二是 dashboard 接口本身返回了空数据，但 MCP 服务端没有正确处理。

排查时，先在 agent-toolkit 里看实际传的参数是什么，然后手动用同样的参数调用 dashboard 接口，看返回什么。如果手动调用有数据，但工具调用没有，那问题就在 MCP 服务端的处理逻辑上。如果手动调用也是空，那说明参数确实不对，需要调整 Agent 的参数提取逻辑或工具描述。

我遇到过一次是因为 dashboard 接口对 task_id 的大小写敏感，而 Agent 传的是大写，dashboard 里存的是小写。解决方案是在 MCP 服务端做一次大小写转换，或者在工具描述里明确说明"task_id 不区分大小写"。

5.3 超时与重试：给工具调用加上合理的边界

超时和重试是分布式调用中绕不开的问题。MCP 工具调用涉及 Agent、MCP 服务端、dashboard 三个环节，任何一个环节慢了都可能导致整体超时。

我的做法是在 MCP 服务端设置两层超时：连接超时 3 秒，读取超时 5 秒。如果 dashboard 在 5 秒内没返回，就主动断开并返回超时错误。同时，对于幂等的查询操作，可以配置一次重试，但重试间隔要短，比如 1 秒，避免堆积请求。

Agent 侧也有超时配置，通常比 MCP 服务端的超时略长，比如 10 秒。这样如果 MCP 服务端因为某种原因没及时返回，Agent 不会无限等待。超时后 Agent 会收到一个超时错误，可以根据业务逻辑决定是重试还是提示用户。

注意：重试不是万能的。对于非幂等的操作，重试可能导致重复执行。查询类工具通常幂等，可以重试；但写入类工具要谨慎，最好在 MCP 服务端做去重或幂等键。

6. 从验证通过到稳定运行的经验沉淀

6.1 工具描述的迭代优化：让 Agent 更懂你的工具

工具描述不是写一次就完事的。在实际使用中，我发现 Agent 经常因为描述不够清晰而调用错误。比如query_task_status和query_task_log两个工具，如果描述里没写清楚区别，Agent 可能会混用。

优化的方法是：每次发现 Agent 调用错误，就回头看看工具描述哪里可以更明确。可以补充使用场景的说明，比如"当你需要了解任务是否完成时使用本工具；当你需要查看任务执行细节时使用 query_task_log"。也可以补充反例，比如"本工具不返回日志内容，日志请使用 query_task_log"。

另外，参数描述也可以迭代。如果发现 Agent 经常把某个参数传错格式，就在描述里加一个示例。比如task_id的描述可以写成"32 位十六进制字符串，例如 a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"。

6.2 监控与告警：给 MCP 调用加上可观测性

工具调用上线后，不能只靠人工测试来保证稳定性。需要加上监控和告警，及时发现异常。我在 MCP 服务端加了几个关键指标：调用次数、成功率、平均耗时、错误分布。这些指标可以输出到日志，也可以推送到监控系统。

告警规则可以设得简单一些：成功率低于 95% 持续 5 分钟就告警，平均耗时超过 3 秒持续 5 分钟就告警。告警渠道可以用邮件或内部消息工具。这样即使半夜出问题，也能及时知道。

还有一个容易被忽略的点：MCP 服务端本身的资源使用情况也要监控。如果服务端进程内存泄漏或者 CPU 跑满，工具调用也会受影响。可以给服务端进程加上资源限制，比如内存不超过 256MB，超了就自动重启。

6.3 版本管理与回滚：工具变更的安全网

MCP 工具的定义和实现会随着业务变化而更新。每次更新都是一次风险，需要有一套版本管理和回滚机制。我的做法是：工具定义文件纳入版本控制，每次变更都提交记录；MCP 服务端的代码也走正常的代码审查和发布流程。

发布时采用灰度策略：先在一个测试环境验证，通过后再发布到生产环境。生产环境发布后，观察一段时间监控指标，确认没有异常才算完成。如果发现问题，立即回滚到上一个版本。回滚要足够快，所以 MCP 服务端的部署包要保留最近几个版本，随时可以切换。

另外，工具定义的变更要通知到使用方。如果某个工具的参数变了，或者某个工具下线了，要提前告知相关团队，避免他们的 Agent 配置失效。可以维护一个工具变更日志，记录每次变更的内容和时间。

6.4 安全边界：MCP 服务端不该做的事

MCP 服务端是 Agent 和外部系统之间的桥梁，它的安全边界很重要。有几件事是 MCP 服务端不应该做的：第一，不应该暴露内部系统的敏感信息，比如数据库连接串、内部 IP、密钥等；第二，不应该执行未经校验的输入，所有参数都要做格式和范围检查；第三，不应该有写入权限，除非业务确实需要，且做了严格的权限控制。

我在实现时遵循了最小权限原则：MCP 服务端只能读取 dashboard 的指定接口，不能写入；只能访问指定的 dashboard 实例，不能访问其他内部系统；只能使用只读的鉴权 token，不能使用管理员 token。这样即使 MCP 服务端被攻破，影响范围也有限。

还有一点：MCP 服务端的日志里不要记录敏感信息。比如鉴权 token 不要打到日志里，用户输入的参数如果包含敏感信息也要脱敏。这些细节在开发时容易忽略，但安全审计时都是问题。

7. 写在最后的一点个人体会

这套 MCP 工具接入方案跑通之后，最大的感受是标准化带来的便利。以前给 Agent 加一个外部能力，可能要改 Agent 的代码、重新部署、测试一堆东西。现在只需要写一个 MCP 工具定义，注册到配置文件里，重启 Agent 就能用。这种解耦设计让工具扩展变得非常轻量。

另一个体会是，工具描述的质量直接决定了 Agent 的使用体验。描述写得清楚，Agent 调用准确率就高；描述写得模糊，Agent 就经常犯错。所以我在工具描述上花的时间，比写实现代码还多。这可能是很多开发者容易忽略的地方。

最后分享一个小技巧：在 MCP 服务端加一个"健康检查"工具，返回服务端的状态和版本信息。这样在排查问题时，可以先调用这个工具确认服务端是否正常，省去很多猜测。这个工具本身不查任何外部数据，实现简单，但很实用。