# 内置 MCP 服务

[Agent HUD 文档](https://agenthud.app/docs/zh/)

Agent HUD 内置的 MCP 服务让你的 agent 读取它的数据、回答用量问题，并以草稿形式改造 HUD，只有你能保存。

更新于 2026-10-29

Agent HUD 内置了一个 MCP 服务。通过它，你平时用的 agent 可以按你的描述重排、重绘 HUD，用应用已有的数据回答关于用量和会话的问题；在发行版里，它们还能彼此发消息。你可以对 agent 说「把 Codex 放在前面，只保留我关心的数据」，或者问「这周哪个会话用的 Token 最多？」。

这些都在你的 Mac 上完成，不需要 Agent HUD Remote。

## agent 能做什么

| | 涵盖的内容 |
| --- | --- |
| **改造 HUD** | 悬停面板的布局：显示哪些区块、行、账户与分区，顺序如何，用进度条、圆环、数字还是图表，间距与宽度多少。每块屏幕上静止的 HUD：形态、停靠边、位置、大小、光晕、外观与透明度。悬停时机等应用设置，只在你明确要求时才改。 |
| **回答用量问题** | 按 agent、模型和时段的 Token，按标价的费用估算，某个会话的用量，过去与当前的会话，以及 agent 在哪些钟点工作。答案来自应用已有的数据，提问不会向厂商发起新的读取。 |
| **彼此发消息** | 在发行版中：给另一个 agent 的会话发消息，或者开一个新会话。过去的只有这条消息，不是整段会话。见 [Agent 互发消息](https://agenthud.app/docs/zh/mcp/messaging/)。 |

## 接入一个 agent

### 允许使用工具

打开 Agent HUD 的**设置 → 智能体插件**，在页面底部的**智能体工具**下打开**允许智能体调整 HUD**。在你打开之前，它一直是关着的。用量问答也归这个开关管：它关着时，所有 HUD 工具与用量工具都会拒绝调用。

![设置 → 智能体插件的「智能体工具」一节：允许智能体调整 HUD、允许 agent 互发消息已打开，以我的身份发送已关闭，连续来回上限为 10](https://agenthud.app/docs/images/settings/agent-plugins-agent-tools.zh.webp)

### 加到你的 agent 里

在 Claude Code、Codex、Cursor、DeepSeek Harness 或 Antigravity 的卡片上，找到 **HUD 工具**这一行，点**添加**。Agent HUD 会把名为 `agent-hud` 的 MCP 服务写进这个 agent 的设置，同时加入一个教 agent 怎么用它的技能 `customize-agent-hud`。agent 可以使用时，这一行显示**可以使用**。

![设置 → 智能体插件：Claude Code 与 Codex 卡片上的「HUD 工具」行都显示「可以使用」](https://agenthud.app/docs/images/settings/agent-plugins-hud-tools.zh.webp)

### 其他 MCP 客户端

其他 agent 用**其他智能体 → 拷贝配置**，把这段配置粘贴到它的 MCP 设置里。

### 新开一个会话

agent 在会话开始时加载工具，已经开着的会话看不到新加的工具。

> **把 Agent HUD 放在「应用程序」里**
>
> 只有装在「应用程序」里的 Agent HUD 才能把 HUD 工具加进 agent。从源码构建的版本，用**拷贝配置**手动添加。

agent 显示工具名时可能带着服务名前缀：Claude Code 里的 `draft_hud` 叫作 `mcp__agent-hud__draft_hud`。

## 草稿，以及怎样保留

agent 从不直接保存对 HUD 的改动。它提出一份草稿，草稿立即显示：

- 面板上标出**布局未保存**、**HUD 样式未保存**或**应用设置未保存**，旁边是**丢弃**和**保存**。把指针移到 HUD 上，点**保存**才会保留。
- 没人保存的草稿，Agent HUD 重启后丢弃。
- agent 调整布局期间，即使指针不在上面，面板也会保持打开，最长两分钟。agent 改完会结束这段保持；你接手时它也立即结束：按 Esc，把指针移进面板再移开，打开设置或统计，或者拖动 HUD。
- 想撤销已保存的改动，在**设置 → 显示**的 **HUD 样式**与**面板布局**里用**恢复之前**或**恢复默认**。

只有一个工具例外：`hud_set_preference` 会立即保存应用的外观（深色、浅色或跟随系统）或动画开关。agent 只在你要求改这一项时才用它。

{/* figure: 悬停面板上显示「布局未保存」，以及「丢弃」和「保存」 */}

## agent 截取的画面

agent 可以截一张面板或某块屏幕上静止 HUD 的图来检查效果。图里的账户会被遮住，会话标题不会出现，而且只截 Agent HUD 自己的画面，从不截你的桌面。

## 工具

**HUD 工具**

| 工具 | 作用 |
| --- | --- |
| `get_hud` | 读取悬停面板的布局、各块屏幕、每块屏幕的 HUD 样式与应用设置，包括未保存的草稿。 |
| `draft_hud` | 提出一份完整的面板布局、一块屏幕的 HUD 样式或应用设置，作为草稿等你保存。 |
| `discard_hud_draft` | 丢弃一块屏幕的布局与 HUD 样式草稿。 |
| `finish_hud_edit` | 结束面板的保持，让面板可以收起。草稿仍等你点**保存**。 |
| `get_hud_screenshot` | 渲染悬停面板、某个 agent 单独的面板或一块屏幕上静止的 HUD，账户会被遮住。 |
| `hud_set_preference` | 在你要求时，立即保存外观或动画设置。 |

**用量与会话**

| 工具 | 作用 |
| --- | --- |
| `hud_snapshot` | 读取当前快照：近期与进行中的会话、Token 合计、每个 agent 的状态。 |
| `hud_refresh` | 读取运行中的应用最近发布的快照，不发起新的读取。 |
| `hud_sessions` | 分页读取应用已收录的会话，可按 agent、项目、范围或关键词筛选。 |
| `hud_session` | 读取一个会话记录下的用量、它的父会话与子 agent。 |
| `hud_statistics` | 读取一段时间的用量：按模型与 agent 的明细、按标价的费用估算，以及按本地钟点的活动。 |
| `hud_capabilities` | 读取这个版本实现了哪些功能。 |

**Agent 消息**（仅发行版，**允许 agent 互发消息**打开时列出）

| 工具 | 作用 |
| --- | --- |
| `list_sessions` | 列出这台 Mac 上 Claude Code、Codex、Antigravity 与 DeepSeek Harness 的会话，以及哪些能收消息。 |
| `send_message` | 给另一个会话发一段文字，或者回复收到的消息。 |
| `start_session` | 以第一条消息开一个新的 Claude Code、Codex 或 Antigravity 会话。 |
| `get_message` | 查看发出的消息到了哪一步，有回答时取回回答。 |

## 工具拒绝调用时

| agent 说 | 怎么办 |
| --- | --- |
| 没有 `get_hud` 或 `draft_hud` 工具 | 在**设置 → 智能体插件**里给这个 agent 添加 **HUD 工具**，然后新开一个会话。 |
| 「Local tools are disabled」 | 打开 Agent HUD，再打开**允许智能体调整 HUD**。 |
| 「Application data is loading」 | Agent HUD 刚启动。agent 等几秒再试一次即可。 |
| 提议被拒绝并附上原因 | 面板或 HUD 无法按要求画出来。什么都没有改变，agent 调整后重新提议。 |

---

English: https://agenthud.app/docs/en/mcp/