Harness MCP Server 把 AI 客户端连接到真实的 Harness 平台资源。看到工具列表只证明协议接通；上线还要证明它用了正确身份、只能看测试范围、未知资源会失败、写操作会按预期停在确认处，而且撤销后不再可用。
本课固定一个非生产项目、一个最小权限身份和金丝雀 HARNESS-MCP-742，完成 M01–M14。首次实验只选一个客户端、一个项目和一条认证路线，不同时配置多个编辑器。
本站验证范围： 本页于 2026-09-10 核读 Harness 当前官方文档。官方当前描述为 11 个通用工具、30 个 toolsets 和 139 种 resource type；实际可见能力还受版本、许可和 RBAC 影响。本站未登录 Harness、创建 PAT、完成 OAuth 或调用真实资源。
下载两份实验材料
验收表的“实际结果”和“状态”默认留空。运行卡只记录凭据的负责人、保管位置和撤销时间，不要粘贴 PAT、OAuth token、密码或完整请求头。
先理解调用链
你的任务
→ Cursor / Claude / VS Code 等 MCP 客户端
→ 11 个通用工具（list / get / create / update / delete / execute …）
→ Registry 根据 resource_type 选择 Harness API
→ Harness 身份、RBAC、资源范围与平台审计harness_list 并不只对应一种资源。它会根据 resource_type 路由到 organization、project、pipeline、execution 等定义。工具数量少不代表权限面小；应同时限制身份、项目、toolset 和操作类型。
M01：固定实验合同
在运行卡填写：
| 字段 | 首轮建议 |
|---|---|
| 账号 / org / project | 单独测试项目，禁止生产项目 |
| 客户端 | Cursor、Claude Code、Claude Desktop、VS Code 或 Windsurf 选一个 |
| 认证 | Hosted OAuth 或自托管 PAT 二选一 |
| 允许资源 | organization、project、pipeline、execution |
| 允许动作 | M01–M10 只允许 list / get |
| 写入样本 | 名称含 HARNESS-MCP-742 的测试草稿 |
| 硬停止 | 身份不明、能看到越界项目、秘密值出现在输出、拒绝后仍写入 |
保存测试项目里一个已存在 pipeline 的 identifier 和一次 execution ID，后面所有正例都指向这两个对象。
M02：选择 Hosted 或自托管路线
Hosted MCP 适用于 Harness SaaS。它通过 Harness ID OAuth 沿用当前用户 RBAC，客户端不保存 Harness API key；账号需先启用 OAuth，SAML/OIDC 账号还要配置 MCP 专用回调。首轮应给登录用户分配测试项目只读角色。
harness-mcp-v2 适用于本地 stdio、自托管 HTTP、Docker 或 Kubernetes。单用户模式使用 PAT / service account token，多用户 HTTP 可逐 session 提供凭据。首轮应设置 HARNESS_READ_ONLY=true 并把 HARNESS_TOOLSETS 缩到实际需要的范围。
Hosted 默认地址为 https://mcp.harness.io/mcp；专属集群或非默认区域应向 Harness 确认地址。若普通网页登录成功但 Hosted MCP 仍报 invalid credentials，先确认账号是否开通 OAuth。
M03：创建最小权限身份并记录撤销点
自托管路线使用专门的短期 PAT 或 service account token，不复用管理员 token。限制到实验 project 的查看权限，并在密码管理器记录 owner、用途、到期与撤销入口。
Hosted 路线不把 API key 写进客户端，但 OAuth 使用当前 Harness 用户身份。先把该用户在测试项目中的 RBAC 收紧，再开始连接。
日志、截图和 CSV 只写凭据指纹末四位或内部编号。Harness secret 资源按官方说明只返回 metadata、不返回值；若看到秘密正文，立即停止实验并按泄露处置。
M04：自托管路线先验证运行环境
Hosted 用户直接进入 M05。本地路线先记录：
node --version
npx --version
which node
which npx再用临时 shell 启动只读服务，确认包能运行后终止：
HARNESS_API_KEY='<只在当前 shell 提供>' \
HARNESS_ORG='<test-org>' \
HARNESS_PROJECT='<test-project>' \
HARNESS_TOOLSETS='platform,pipelines' \
HARNESS_READ_ONLY=true \
npx -y harness-mcp-v2@latest不要把 token 写进版本库。GUI 客户端经常不继承 shell PATH；若报 npx ENOENT 或 node: No such file or directory，使用 M04 记录的绝对路径，并显式设置最小 PATH。
M05：只配置一个客户端
路线 A：Hosted OAuth
Cursor：
{
"mcpServers": {
"harness-hosted": {
"url": "https://mcp.harness.io/mcp",
"auth": { "CLIENT_ID": "mcp-client" }
}
}
}Claude Code：
claude mcp add --transport http \
--client-id mcp-client \
harness-hosted-mcp https://mcp.harness.io/mcpVS Code 的 .vscode/mcp.json：
{
"servers": {
"harness-hosted": {
"type": "http",
"url": "https://mcp.harness.io/mcp"
}
},
"inputs": []
}保存后完成 Harness ID 登录。若企业使用 SAML/OIDC，IdP 必须包含 Harness 给出的 MCP 专用 ACS URL 或 redirect URI。
路线 B：本地 stdio
以 Cursor 的 .cursor/mcp.json 为例：
{
"mcpServers": {
"harness": {
"command": "/absolute/path/to/npx",
"args": ["-y", "harness-mcp-v2"],
"env": {
"HARNESS_API_KEY": "<由本机秘密方案注入>",
"HARNESS_ORG": "<test-org>",
"HARNESS_PROJECT": "<test-project>",
"HARNESS_TOOLSETS": "platform,pipelines",
"HARNESS_READ_ONLY": "true",
"PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
}
}
}
}Claude Desktop 顶层同样使用 mcpServers，macOS 配置路径是 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 是 %APPDATA%/Claude/claude_desktop_config.json。VS Code 本地配置外层使用 {"mcp":{"servers":{...}}}。复制前对照官方当前客户端页，不要在客户端之间照搬外层 schema。
M06：重启客户端并盘点实际能力
彻底退出并重新打开客户端。记录 MCP server 状态、启动时间和实际工具名；不要只看“绿色圆点”。先要求：
列出当前连接提供的 Harness MCP 工具名称，不调用任何写工具。
再用 harness_describe 说明 organization、project、pipeline、execution 四种 resource_type 的可用操作。
缺失或未知项明确写出，不要猜测。通过条件是能看到实际工具，并能区分 resource type 与操作。Hosted 可见资源受许可影响，不要求机械出现 139 种。
M07：用正例证明身份与范围
要求客户端依次：
harness_list(resource_type="organization")，找到预期 test org。harness_list(resource_type="project", org_id="<test-org>")，找到预期 test project。harness_get(resource_type="pipeline", ...)，读取 M01 固定 pipeline。harness_get(resource_type="execution", ...)，读取固定 execution。
把 resource identifier、结果数量、execution 状态和 Harness deep link 写进验收表。自然语言总结本身不算证据，必须能回到准确资源。
M08：用越界负例证明最小权限
请求读取一个已知存在、但该实验身份没有权限的其他项目。预期是拒绝、不可见或空结果，具体表现以 RBAC 为准；返回越界项目详情就是硬失败。
再请求不存在的 project_id="HARNESS-MCP-742-NOT-FOUND"。记录 not found 与 permission denied 的实际差异，避免日后把权限问题误诊为资源不存在。
M09：用金丝雀验证只读问答
针对固定失败 execution 提问：
只读取这一次 execution。输出 pipeline identifier、execution identifier、commit、首个失败步骤、退出状态与对应 deep link。
观察不到的字段写“未知”。不要重跑、更新、创建或删除任何资源。
最后一行原样输出 HARNESS-MCP-742。通过条件：标识与平台页面一致、结论能回到当前 execution，且没有写调用。只复述金丝雀不能证明读取成功。
M10：验证工具发现与错误恢复
故意调用不存在的 resource_type="pipeline_typo_742"。预期返回 unknown resource type；随后使用 harness_describe 搜索正确类型，再重新读取固定 pipeline。
若项目级调用提示缺少 path 参数，显式传 org_id / project_id，或核对 HARNESS_ORG / HARNESS_PROJECT。不要通过扩大账号权限修复字段缺失。
M11：证明只读模式真的挡住写入
在 HARNESS_READ_ONLY=true 或只读 RBAC 下，请求创建一个只含 HARNESS-MCP-742 名称的测试草稿。预期 create 被拒绝，随后 list/get 证明资源不存在。
若资源被创建，停止实验：检查启动的是不是另一套 MCP 配置、环境变量是否生效、Hosted 登录用户是否拥有超出预期的角色。
M12：在隔离项目验证确认机制
只有 M01–M11 全部通过，才为同一身份增加测试项目内的最小创建权限，并关闭本地 HARNESS_READ_ONLY。当前官方表列出 Cursor、VS Code Copilot 和 MCP Inspector 支持 elicitation；Claude Desktop、Windsurf 尚不支持。
在支持 elicitation 的客户端做两次：
- 请求创建
HARNESS-MCP-742-decline，看到完整摘要后拒绝，再证明资源不存在。 - 请求创建最小测试草稿
HARNESS-MCP-742-accept，核对 org/project/type/name 后接受，再用 get 读取准确 ID。
不支持 elicitation 的客户端中，create、update、execute 可能无对话框继续，delete 默认会被阻止。此时不要做 M12 写入实验；维持只读模式或只读 RBAC，并写“客户端不支持，未执行”。
不要设置 HARNESS_AUTO_APPROVE_RISK=all。它会跳过包括 delete 在内的确认。自动任务若确有需要，只在独立环境从 low_write 起步并缩小 toolsets；HTTP session header 只能把部署阈值收紧，不能放宽。
M13：检查日志、审计与故障证据
本地 stdio 可设置：
HARNESS_MCP_LOG_FILE=/approved/local/path/harness-mcp.log
HARNESS_AUDIT_FILE=/approved/local/path/harness-mcp-audit.ndjson
LOG_LEVEL=info核对 M07、M08、M11、M12 的时间、操作、资源类型、结果和操作者能否追踪，并确认没有 PAT 或 secret value。HTTP 入口还应验证：非 loopback bind 需要 HARNESS_MCP_AUTH_TOKEN，默认 Host 校验、same-origin CORS、每 IP 每分钟 60 次限制，以及 Harness API 客户端每秒 10 次限制。
若报 mcp-session-id 缺失，先 initialize，再在后续 /mcp 请求携带同一 session ID；空闲 30 分钟后 session 会过期。VS Code 出现 401/404 重连循环时，按官方排错页移除缓存的 dynamic authentication provider，再重连 OAuth。
M14：撤销并证明入口失效
- 删除或禁用客户端里的 Harness MCP 配置。
- Hosted 路线撤销 OAuth session；自托管路线停止进程并撤销测试 token。
- 回收 M12 临时创建权限；测试草稿按团队流程清理并保存删除记录。
- 重启客户端，确认 Harness 工具列表消失或连接不可用。
- 用旧 token / 旧 session 做一次只读负例，预期认证失败；不要把秘密值写入验收表。
只有“配置移除 + 身份撤销 + 权限回收 + 客户端复验”全部有证据，才算完成。停止一个进程不能证明 OAuth 或 PAT 已失效。
常见失败定位
- **Hosted invalid credentials：**先查账号是否启用 OAuth；修复后重新连接并完成 Harness ID 登录。
- **SAML/OIDC reply URL mismatch：**先查 IdP 是否加入 MCP 专用回调；修复后从客户端重新发起登录。
- **GUI 报
npx ENOENT：**先查command与 PATH 是否为绝对可用路径；重启后重新盘点工具。 - **unknown
resource_type：**先查拼写与HARNESS_TOOLSETS；用harness_describe找到正确类型后重试。 - **缺 org/project 字段：**先查默认范围或本次参数；显式传 identifier 后重试。
- **write not allowed：**先查
HARNESS_READ_ONLY与 RBAC，并确认本轮是否真的需要写。 - **pipeline 缺 runtime inputs：**先读取
runtime_input_template；补齐 inputs 或 input set 后再在测试项目重试。 - **拒绝后仍发生写入：**立即撤销 token，检查实际配置、auto-approve 阈值和审计记录。
最终验收门槛
- M01–M14 每行都有时间、实际证据和状态，未执行项有原因。
- 正例只能访问指定测试 org/project，越界与不存在资源的负例可区分。
- 只读模式阻止 create/update/delete/execute，而不是只靠提示词约束。
- 支持 elicitation 的客户端完成一次拒绝不落地与一次受控接受；不支持者没有冒充通过。
- 日志和审计能定位操作但不包含秘密值。
- 客户端配置、token/OAuth、临时权限和测试资源均有撤销记录。
接下来若要理解 MCP 与 Agent 运行框架的分层，完成 Agent Harness H01–H12 实验；若要把失败分析放进 Pipeline，再进入 Harness Worker Agents W01–W14 实验。