# MCP 集成（AI Agent 接入） (/zh/docs/integration/mcp)



Herald 提供官方 MCP（Model Context Protocol）服务，你的 AI agent 可以用结构化的工具语义查询租户数据，而不必阅读 REST 文档后手写调用。授权走 OAuth：你在浏览器里用自己的 Herald 账号登录一次，agent 持有用户凭证——不需要 API Key，不需要 client id，也不需要粘贴任何 secret。

端点是标准 MCP Streamable HTTP 端点（协议版本 2026-07-28），由你的 Herald 实例自身提供——与 REST API 同源，无需独立部署。Herald 的 MCP 服务**不接受** API Key。

## 1. 获取租户地址 [#1-获取租户地址]

每个租户有唯一的 canonical MCP 地址：

```text
https://<origin>/mcp/<realmId>
```

* `<origin>`——你的 Herald 部署源（或租户配置的自定义域名）
* `<realmId>`——你的租户 ID

租户 ID 是地址的一部分：为一个租户签发的凭证拿到另一个租户的地址上必然失效。

## 2. 连接你的 Agent 客户端（仅需 URL） [#2-连接你的-agent-客户端仅需-url]

客户端只需要租户地址，不需要其他任何输入。客户端会通过 RFC 9728 / RFC 8414 发现与受控的 RFC 7591 注册端点，自动取得本租户预置的公共 MCP 客户端（`herald-mcp`）。

> **先开启租户的 MCP 接入**：内置的 Herald MCP 客户端默认停用。租户管理员需先在管理后台 Client App 列表中启用它，agent 才能完成注册与授权（见第 7 节的租户开关）。

**Claude Code**——已在 Claude Code 2.1.269 上完成端到端验证：仅凭 URL 即可完成注册、浏览器授权、工具发现与工具调用。

```bash
claude mcp add --transport http herald https://your-herald-host/mcp/your-realm-id
```

**VS Code**（`.vscode/mcp.json`，或 MCP: Add Server → HTTP）——消费与上面验证过的同一套发现与注册契约（已对照 VS Code 1.140 检查）；VS Code 内的交互式 OAuth 握手尚待端到端验证。

```json
{
  "servers": {
    "herald": {
      "type": "http",
      "url": "https://your-herald-host/mcp/your-realm-id"
    }
  }
}
```

其他实现了 MCP 授权规范（受保护资源发现、浏览器 PKCE 授权、动态客户端注册）的 MCP 客户端应可同样接入——同样只填租户地址。

## 3. 浏览器登录一次 [#3-浏览器登录一次]

首次连接时，客户端会拉起 Herald 登录页。像平常一样登录——包括租户启用的协议确认或二次认证。浏览器回跳后，工具即可使用。

登录完成前关闭浏览器只是不签发凭证；从客户端重新连接再试即可。授权过期或被吊销后，客户端会以同样方式引导重新授权。

## 4. 九个只读工具 [#4-九个只读工具]

### 管理工具 [#管理工具]

按**授权用户的 RBAC 权限**放行——需要为用户授予带对应权限的角色，而不是配置某个 key：

| 工具                         | 作用             | 所需权限            |
| -------------------------- | -------------- | --------------- |
| `query_users`              | 查询租户用户列表或详情    | `users.view`    |
| `get_points_balance`       | 指定用户的租户范围积分余额  | `points.view`   |
| `list_points_transactions` | 指定用户的积分流水，最新在前 | `points.view`   |
| `list_audit_logs`          | 查询租户审计日志       | `audit.view`    |
| `get_realm_config_status`  | 查询各配置项的存在与启用状态 | `settings.view` |

管理余额工具返回的是目标用户**整个租户范围**的余额，不按 client app 收窄。配置状态在任何情况下都不返回配置值。

### 本人工具 [#本人工具]

一律只作用于**授权用户本人**。这些工具不接受 `userId`——要求查询他人会被拒绝：

| 工具                            | 作用        | 所需 scope                 |
| ----------------------------- | --------- | ------------------------ |
| `get_my_profile`              | 我的资料      | `mcp:profile:read`       |
| `get_my_points_balance`       | 我的积分余额    | `mcp:points:read`        |
| `list_my_points_transactions` | 我的积分流水    | `mcp:transactions:read`  |
| `list_my_subscriptions`       | 我的订阅与权益状态 | `mcp:subscriptions:read` |

任何被授予对应 scope 的 Herald 用户都可以调用本人工具——不需要管理员角色。

### 共同约定 [#共同约定]

* 分页从 1 开始，默认 `page=1` / `pageSize=20`，最大 100。
* 时间过滤接受 RFC 3339 时间戳或 `YYYY-MM-DD`（按 UTC 零点解释）。
* 返回字段刻意收窄——agent 可能把结果带入第三方模型：不透出 IP、User Agent、Trace ID、配置值或支付元数据。
* 只读是刻意设计。写操作被有意排除，只会在逐工具安全评审后按工具逐步加入。需要写入数据或完整字段面时，请改用客户端凭证调用 REST API——参见[第三方后端集成指南](/zh/docs/integration/third-party-backend)与 [OpenAPI 参考](/zh/docs/api)。

## 5. 连通性自检 [#5-连通性自检]

连接完成后，让 agent 执行：

> 使用 herald 的 `get_my_profile` 工具。

该工具零入参、只读取你本人的资料、除 profile scope 外不需要任何管理权限。成功返回你的 id 与邮箱，即证明「发现 + 客户端注册 + 浏览器授权 + 取数」全链路可用。

## 6. 排障 [#6-排障]

| 症状                                                                     | 原因                                         | 恢复方式                                             |
| ---------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------ |
| 工具返回 `permission_denied`——"Your user does not have the 'X' permission" | 管理工具按授权用户的 RBAC 放行                         | 请租户管理员为你授予带该权限的角色；重新登录无效                         |
| HTTP 403 且带 `insufficient_scope` 挑战                                    | 本次授权未授予本人工具所需 scope                        | 在 agent 客户端重新授权，并接受请求的 scope                     |
| 每次调用都返回 HTTP 401 授权挑战                                                  | 凭证缺失、过期或被吊销——或租户已停用 MCP 接入                 | 重新授权；若租户停用了 MCP，请管理员重新启用后再重新授权（旧授权不会复活）          |
| 连接时 HTTP 404                                                           | 租户地址不对                                     | 检查 `https://<origin>/mcp/<realmId>`——含租户 ID，无尾斜线 |
| `invalid_target` / `invalid_scope` 错误                                  | 授权请求被篡改或客户端配置有误                            | 删除后仅用租户地址重新添加服务                                  |
| 工具返回 `not_found`                                                       | 目标 id 不存在——或属于其他租户（跨租户 id 一律表现为 not found） | 检查 id；agent 无法查询授权租户之外的数据                        |
| 工具返回 `invalid_argument`                                                | 参数畸形——错误信息会指明字段与期望格式                       | 按提示修正后重发（如合法 UUID、`startTime` 不晚于 `endTime`）     |
| 工具返回 `internal_error`                                                  | 服务端故障                                      | 重试；持续出现请查看服务端日志                                  |

## 7. 凭证、隔离与限额 [#7-凭证隔离与限额]

* **凭证双向隔离：** MCP 凭证代表你本人，但与浏览器/管理台会话相互独立——两侧互不接受对方凭证。
* **长会话：** 客户端通过标准刷新授权续期；refresh token 轮换且有绝对上限。
* **即时吊销：** 账号被禁用、被强制下线或租户内置 MCP 客户端被停用的那一刻，你的 MCP 凭证立即失效。
* **租户开关：** 每个租户在管理后台 Client App 列表中有一个内置的「Herald MCP」客户端。停用即关闭本租户 MCP 接入——已有与新增授权全部被拒绝。重新启用不会复活旧授权，agent 需重新授权。内置客户端不可删除。
* **限流：** 每个授权用户的 MCP 调用限额为 60 次 / 60 秒。