Harness

Harness MCP Server 2.0

一个 MCP（Model Context Protocol）服务，通过 11 个整合工具和 263 种资源类型，为 AI Agent 提供对 Harness.io 平台的完整访问权限。

为什么使用此 MCP 服务

大多数 MCP 服务为每个 API 端点对应一个工具。对于 Harness 这样覆盖范围广泛的平台，这意味着需要 240 多个工具——而随着工具数量增加，大模型选择工具的能力会变差。上下文窗口会被各种架构定义占满，每增加一个新端点，就意味着要编写新代码。

此服务采用了不同的设计：

• 11 个工具，263 种资源类型。 基于注册表的分发系统会将 harness_list、harness_get、harness_create 等工具路由到任意 Harness 资源——包括流水线、服务、环境、组织、项目、功能标志、成本数据等。大模型只需从 11 个工具中选择，而不是数百个。
• 覆盖整个平台。 42 个默认工具集涵盖 CI/CD、GitOps、功能标志、云成本管理、安全测试、混沌工程、数据库 DevOps、内部开发者门户、软件供应链、基础设施即代码管理、发布管理、治理、服务覆盖项、知识图谱等。需要时，还可以选择启用 Ansible 和可观测性评估功能。
• 开箱即用的多项目工作流。 Agent 可动态发现组织和项目，无需硬编码环境变量。只需询问“显示所有项目中的失败执行”，Agent 就可以遍历整个账户层级。
• 35 个提示词模板。 为常见工作流预先构建的提示词：端到端构建和部署应用、调试失败的流水线、查看 DORA 指标、分类处理漏洞、优化云成本、审计访问控制、规划功能标志发布、审查拉取请求、批准待处理的流水线等。
• 随处可用。 为本地客户端（Claude Desktop、Cursor、Devin Desktop）提供 Stdio 传输，为远程/共享部署提供 HTTP 传输，并支持 Docker 和 Kubernetes。
• 零配置启动。 只需提供 Harness API 密钥。账户 ID 会从 PAT 和 SAT 令牌中自动提取；组织/项目默认值为可选项，工具集筛选功能可让你只公开所需内容。
• 设计上易于扩展。 添加新的 Harness 资源只需添加声明式数据文件，无需注册新工具、修改架构或更新提示词。

前提条件

安装或运行服务之前，你需要准备 Harness API 密钥：

1. 登录你的 Harness 账户
2. 前往 My Profile → API Keys → + New API Key
3. 在 API 密钥下创建新的 Token——这会生成格式为 <prefix>.<accountId>.<tokenId>.<secret> 的 PAT 或 SAT
4. 将令牌保存在安全的位置——下一步需要用到

如需详细说明，请参阅 Harness API 快速入门。

快速开始

选项 0：托管 Harness MCP

如果你的 Harness 账户已启用托管 MCP 服务，支持远程 MCP 服务的客户端可以直接连接到托管端点，而无需在本地运行服务。

重要： 托管 MCP 服务使用的是 Harness Platform OAuth，而非 HARNESS_API_KEY。此外，必须先由 Harness Support 为账户启用/配置该服务，才能使用此端点。

配置示例请参阅托管 Harness MCP。

选项 1：npx（推荐）

无需安装，直接运行：

HARNESS_API_KEY=pat.xxx.xxx.xxx npx harness-mcp-v2@latest

或者在 AI 客户端中配置 API 密钥（请参阅下文的客户端配置）。

# Stdio transport (default — for Claude Desktop, Cursor, Devin Desktop, etc.)
HARNESS_API_KEY=pat.xxx npx harness-mcp-v2

# HTTP transport (for remote/shared deployments)
HARNESS_API_KEY=pat.xxx npx harness-mcp-v2 http --port 8080

注意： 账户 ID 会从 PAT 和 SAT 令牌中自动提取（pat.<accountId>... 或 sat.<accountId>...），因此只有在 API 密钥中未嵌入账户 ID 时，才需要设置 HARNESS_ACCOUNT_ID。

选项 2：全局安装

npm install -g harness-mcp-v2

# Then run directly
harness-mcp-v2

选项 3：从源代码构建

用于开发或自定义：

git clone https://github.com/harness/mcp-server.git
cd mcp-server
pnpm install
pnpm build

# Run
pnpm start              # Stdio transport
pnpm start:http         # HTTP transport
pnpm inspect            # Test with MCP Inspector

Anthropic MCP 目录包

MCPB 包清单位于 [mcp-directory/](mcp-directory/)，512×512 的包图标存放在仓库根目录的 [icon.png](icon.png)。打包后的归档包含根目录下的 manifest.json、icon.png、server/、package.json、npm-shrinkwrap.json 和生产环境 node_modules/。

为缩小归档体积，请从暂存目录构建 MCPB 包：

pnpm prepare:mcpb

暂存目录会写入 dist/mcpb/，并使用 npm 的扁平布局从 npm-shrinkwrap.json 安装生产依赖。固定版本的官方 MCPB CLI 会验证该目录，并创建 dist/harness-mcp-server-<version>.mcpb。

匹配 v*.*.* 的版本标签会自动将该包发布到对应的 GitHub Release。若要为现有 Release 补发而不重新发布 npm，请手动运行 Release 工作流并填写 release_tag 输入项（例如 v3.2.20）。该工作流会检出并构建对应的精确标签，然后仅替换其带版本号的 MCPB 资源。

CLI 用法

harness-mcp-v2 [stdio|http] [--port <number>]

Options:
  --port <number>  Port for HTTP transport (default: 3000, or PORT env var)
  --help           Show help message and exit
  --version        Print version and exit

如果未指定传输方式，默认使用 stdio。远程或共享部署请使用 http。

HTTP 传输

以 HTTP 模式运行时，服务会公开以下端点：

端点	方法	描述
/mcp	POST	MCP JSON-RPC 端点（初始化和会话请求）
/mcp	GET	用于服务器发起消息（进度、信息征询）的 SSE 流
/mcp	DELETE	终止活动的 MCP 会话
/mcp	OPTIONS	CORS 预检
/health	GET	健康检查 — 返回 { "status": "ok", "sessions": <count> }
/.well-known/oauth-protected-resource	GET	在 oauth 和 oauth-proxy 模式下提供 RFC 9728 元数据
/.well-known/oauth-protected-resource/mcp	GET	针对默认 /mcp 资源提供路径感知的 RFC 9728 元数据
/.well-known/oauth-authorization-server	GET	在 oauth-proxy 模式下提供内嵌代理的 RFC 8414 元数据
/oauth/authorize	GET	通过上游提供方和 HarnessID 启动 MCP 客户端登录
/oauth/upstream/callback	GET	上游身份提供方回调
/oauth/harnessid/callback	GET	HarnessID 登录回调
/oauth/token	POST	为 MCP 客户端返回或刷新上游令牌；绝不返回 HarnessID 令牌

HTTP 传输采用基于会话的模式。收到 initialize 请求时会创建新的 MCP 会话，服务会返回 mcp-session-id 标头，该会话后续的请求必须包含相同的标头。

HTTP 模式下的运行约束：

• 对于共享部署或可远程访问的单用户和多用户部署，请设置 HARNESS_MCP_AUTH_TOKEN。设置后，每个发往 /mcp 的 POST、GET 和 DELETE 请求都必须包含 Authorization: Bearer <token>。
• OAuth 模式接受 HarnessID 访问令牌，而非 HARNESS_MCP_AUTH_TOKEN，并且无需选择退出未认证模式即可绑定到非回环地址。
• 默认情况下，绑定到非回环地址的单用户和多用户部署必须设置 HARNESS_MCP_AUTH_TOKEN。若仍要在非回环接口上运行未认证模式，请显式设置 HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP=true。
• 不带 mcp-session-id 的 POST /mcp 请求必须是 initialize 请求。
• 针对已有会话的 POST /mcp、GET /mcp 和 DELETE /mcp 请求必须包含 mcp-session-id 标头。
• GET /mcp 用于发送 SSE 通知（进度更新和信息征询提示词）。
• 当没有活动请求或 SSE 流时，闲置会话会在 MCP_SESSION_TTL_MS 毫秒后被清理（默认值为 1800000，即 30 分钟）。
• GET /health 是唯一的非 MCP 端点。
• 请求正文大小上限由 HARNESS_MAX_BODY_SIZE_MB 控制（默认值为 10 MB）。
• 在 initialize 请求中设置 x-harness-pipeline-version: 0 或 1，以选择该 HTTP 会话的 V0 或 V1 流水线资源。
• 在 initialize 请求中设置 x-harness-auto-approve-risk: none|low_write|medium_write|high_write|all，以选择更严格的会话级自动批准阈值。服务会将此值限制在部署级 HARNESS_AUTO_APPROVE_RISK 范围内，因此会话只能降低配置的批准上限，不能提高它。

HarnessID OAuth 模式

设置 HARNESS_MCP_MODE=oauth，让远程 MCP 客户端发现 HarnessID，并通过带 PKCE 的 OAuth 2.1 授权码流程完成授权。OAuth 模式仅适用于 HTTP 传输。生产环境中的 HarnessID、MCP 资源和 API 路由默认值已内置：

HARNESS_MCP_MODE=oauth

默认颁发者为 https://id.harness.io/idp/realms/HarnessIDP，资源为 https://mcp.harness.io/mcp，OAuth 客户端为 mcp-client，Harness API 基础 URL 为 https://mcp.harness.io/cli。仅在 QA、本地开发或其他 Harness 环境中覆盖这些值。

此模式下不得设置 HARNESS_API_KEY。HARNESS_MCP_OAUTH_JWKS_URI 默认为 <issuer>/protocol/openid-connect/certs，无需设置 HARNESS_ACCOUNT_ID，因为账户信息来自令牌。

服务会发布 RFC 9728 受保护资源元数据；当客户端尚未通过身份验证时，会返回以下质询：

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.harness.io/.well-known/oauth-protected-resource/mcp"

服务使用配置的 JWKS 端点验证 HarnessID 访问令牌的 RS256 签名、iss、有效期和 sub，并通过 azp 声明检查令牌是否签发给 HARNESS_MCP_OAUTH_CLIENT_ID。HARNESS_MCP_OAUTH_RESOURCE 是用于发现和质询的 RFC 9728 受保护资源标识符。目前的 HarnessID 访问令牌使用 aud: account，而非 MCP URL，因此不会将资源与 aud 进行比较。

账户 ID 来自令牌的 HARNESS_MCP_OAUTH_ACCOUNT_CLAIM 声明（默认为 account_id），该声明由 HarnessID 的 organization scope 填充。每个会话都会保存调用者的访问令牌，并将其作为 Authorization: Bearer 转发给 Harness API，因此 Harness RBAC 和审计记录反映的是已登录用户，而不是共享 PAT。会话会绑定创建时使用的 sub 和账户：后续请求可以携带刷新后的令牌，但如果令牌属于其他用户或账户，则会被拒绝。

客户端通常只需 MCP 资源 URL：

{
  "mcpServers": {
    "harness": {
      "url": "https://mcp.harness.io/mcp"
    }
  }
}

客户端会读取受保护资源元数据，发现 HARNESS_MCP_OAUTH_ISSUER，然后使用该授权服务器的 RFC 8414 元数据。如果客户端不支持动态客户端注册，请使用预先注册的 mcp-client 客户端 ID。

有关 QA Keycloak 检查清单和验证命令，请参阅可自托管 MCP 服务的 HarnessID OAuth。

上游身份提供商 OAuth 代理模式

OAuth 代理模式需要一个机密 HarnessID 客户端。Harness ID 团队会创建该客户端并提供客户端 ID 和客户端密钥。启用此模式前，请联系 Harness ID 团队。

当 MCP 客户端必须仅持有上游身份提供商令牌时，设置 HARNESS_MCP_MODE=oauth-proxy。公共客户端名称可以任意指定。将 HARNESS_MCP_BROKER_CLIENT_ID 设置为 MCP 客户端使用的相同名称。集成式 OAuth 代理会启动上游浏览器登录，并在同一流程中完成 HarnessID 登录，然后仅向 MCP 客户端返回上游访问令牌和刷新令牌。每次收到 /mcp 请求时，服务都会验证上游令牌，并使用按用户缓存的 HarnessID 访问令牌；令牌过期前，会使用刷新令牌续期。如果缺少上游与 HarnessID 之间的映射，则返回 401，要求客户端重新登录。HarnessID 令牌会保留在服务端。刷新令牌、缓存的访问令牌和临时 OAuth 状态均会加密后存储。

此模式仅支持 HTTP。它还需要上游颁发者、受众以及稳定的 32 字节保险库密钥。配置和 端到端 MCP 测试命令请参阅上游身份提供商 OAuth 代理模式。

多用户模式

对于每个客户端都以不同 Harness 用户身份进行身份验证的共享 HTTP 部署，请设置 HARNESS_MCP_MODE=multi-user。在此模式下：

• 服务器配置中不得设置 HARNESS_API_KEY — 服务器不持有 Harness 凭据。
• 每个会话都必须在 initialize 请求中提供 x-harness-api-key。只有当 API 密钥未嵌入账户字段时，才需要提供 x-harness-account-id。
• 会话还可以提供 x-harness-org 和 x-harness-project 标头，为该会话设置默认范围。
• Harness API 密钥会传递给该会话的每次 Harness API 调用，因此 Harness 中的审计跟踪会反映真实用户。
• HARNESS_MCP_AUTH_TOKEN 独立于此，仍可用作额外的传输层关卡。

# Health check
curl http://localhost:3000/health

# MCP initialize request (capture mcp-session-id response header)
# In multi-user mode, x-harness-api-key is required on initialize.
# x-harness-account-id is needed only for API keys without an embedded account segment.
curl -i -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $HARNESS_MCP_AUTH_TOKEN" \
  -H "x-harness-api-key: $HARNESS_API_KEY" \
  -H "x-harness-account-id: $HARNESS_ACCOUNT_ID" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

# Subsequent MCP request (use returned session ID)
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $HARNESS_MCP_AUTH_TOKEN" \
  -H "mcp-session-id: <session-id>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# Terminate session
curl -X DELETE http://localhost:3000/mcp \
  -H "Authorization: Bearer $HARNESS_MCP_AUTH_TOKEN" \
  -H "mcp-session-id: <session-id>"

HARNESS_MCP_ALLOWED_HOSTS 控制用于防止 DNS 重绑定的 Host 标头验证，CORS 则限制浏览器来源。两者都不是身份验证；请使用 HARNESS_MCP_AUTH_TOKEN 或经过身份验证的网关／反向代理进行访问控制。

客户端配置

注意： HARNESS_ORG 和 HARNESS_PROJECT 是可选项。未在工具调用中指定时，它们会设置所使用的组织 ID 和项目 ID。Agent 可以使用 harness_list(resource_type="organization") 和 harness_list(resource_type="project") 动态发现组织和项目。已弃用的名称 HARNESS_DEFAULT_ORG_ID 和 HARNESS_DEFAULT_PROJECT_ID 仍受支持，以保持向后兼容。

托管 Harness MCP

Harness 还为已启用托管服务的账户提供托管 MCP 端点。如果你想使用共享的远程 MCP 端点，而不是运行 npx harness-mcp-v2 或自行托管 HTTP 传输，这会很有用。

重要： 托管 MCP 使用 Harness Platform OAuth 进行身份验证。客户端配置中不使用 HARNESS_API_KEY。托管 MCP 的可用性按 Harness 账户配置，因此使用前需要联系 Harness Support 启用／配置此设置。

托管端点 https://mcp.harness.io/mcp 是一项托管服务。Claude、Cursor 或 Cowork 中的客户端 MCP 配置无法更改其路由到的 Harness 环境。对于 Harness0 或其他私有 Harness SaaS 环境，请联系 Harness Support 为该环境启用／配置托管 MCP，或者运行本地／自托管服务并将 HARNESS_BASE_URL 设置为目标 Harness 主机。

托管 MCP 示例：

{
  "mcpServers": {
    "harness-prod1-mcp": {
      "url": "https://mcp.harness.io/mcp",
      "auth": {
        "CLIENT_ID": "mcp-client"
      }
    }
  }
}

同时包含托管和本地条目的示例：

{
  "mcpServers": {
    "harness-hosted": {
      "url": "https://mcp.harness.io/mcp",
      "auth": {
        "CLIENT_ID": "mcp-client"
      }
    },
    "harness-local": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "harness-mcp-v2@latest"],
      "env": {
        "HARNESS_API_KEY": "pat.xxx.xxx.xxx",
        "PATH": "/directory/containing/node:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

排查 npx ENOENT 或 node: No such file or directory

这是客户端进程启动失败，并非 Harness 身份验证失败。MCP 服务尚未启动，因此更改 HARNESS_API_KEY 不会影响 spawn npx ENOENT。

GUI 应用（Cursor、Claude Desktop、Devin Desktop、VS Code）不一定会继承 shell 的 PATH，因此配置重新加载后可能无法找到 npx 或 node。请使用绝对路径，并在 env 块中显式设置 PATH：

{
  "mcpServers": {
    "harness": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "harness-mcp-v2"],
      "env": {
        "HARNESS_API_KEY": "pat.xxx.xxx.xxx",
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

在终端中运行 which npx 和 which node 查找路径，然后确保包含 node 的目录已包含在上述 PATH 值中。常见位置：

• Homebrew（macOS）： /opt/homebrew/bin/npx
• nvm： ~/.nvm/versions/node/v20.x.x/bin/npx（运行 nvm which current 查找确切路径）
• 系统 Node： /usr/local/bin/npx

Claude Desktop（claude_desktop_config.json）

npx（零安装）

{
  "mcpServers": {
    "harness": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "harness-mcp-v2@latest"],
      "env": {
        "HARNESS_API_KEY": "pat.xxx.xxx.xxx",
        "PATH": "/directory/containing/node:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

node（本地安装）

npm install -g harness-mcp-v2

{
  "mcpServers": {
    "harness": {
      "command": "/absolute/path/to/harness-mcp-v2",
      "env": {
        "HARNESS_API_KEY": "pat.xxx.xxx.xxx",
        "PATH": "/directory/containing/node:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Claude Code（通过 claude mcp add）

npx（零安装）

claude mcp add harness -- npx harness-mcp-v2

node（本地安装）

npm install -g harness-mcp-v2
claude mcp add harness -- harness-mcp-v2

然后在环境变量或 .env 文件中设置 HARNESS_API_KEY。

Cursor（.cursor/mcp.json）

npx（零安装，推荐用于本地 Cursor 配置）

{
  "mcpServers": {
    "harness": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "harness-mcp-v2@latest"],
      "env": {
        "HARNESS_API_KEY": "pat.xxx.xxx.xxx",
        "PATH": "/directory/containing/node:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

在终端中运行 which npx，并将其完整路径用于 command；在 PATH 前面添加 which node 返回的目录。

node（本地安装）

npm install -g harness-mcp-v2

{
  "mcpServers": {
    "harness": {
      "command": "/absolute/path/to/harness-mcp-v2",
      "env": {
        "HARNESS_API_KEY": "pat.xxx.xxx.xxx",
        "PATH": "/directory/containing/node:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

运行 npm install -g harness-mcp-v2 后，执行 which harness-mcp-v2，并将其完整路径用于 command；在 PATH 前面添加 which node 返回的目录。

Devin Desktop（~/.windsurf/mcp.json）

npx（零安装）

{
  "mcpServers": {
    "harness": {
      "command": "/absolute/path/to/npx",
      "args": ["-y", "harness-mcp-v2@latest"],
      "env": {
        "HARNESS_API_KEY": "pat.xxx.xxx.xxx",
        "PATH": "/directory/containing/node:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

node（本地安装）

npm install -g harness-mcp-v2

{
  "mcpServers": {
    "harness": {
      "command": "/absolute/path/to/harness-mcp-v2",
      "env": {
        "HARNESS_API_KEY": "pat.xxx.xxx.xxx",
        "PATH": "/directory/containing/node:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

使用本地源码构建版本？

将命令替换为构建所得 index.js 的路径：

{
  "command": "node",
  "args": ["/absolute/path/to/harness-mcp-v2/build/index.js", "stdio"]
}

MCP 网关

Harness MCP 服务与 MCP 网关完全兼容。MCP 网关是反向代理，可在多个 MCP 服务之间提供集中式身份验证、治理、工具路由和可观测性。由于该服务实现了标准 MCP 协议，并支持 stdio 和 HTTP 传输，因此无需修改代码即可在任何符合 MCP 规范的网关后运行。

为什么使用网关？

• 集中管理凭据——Agent 配置中无需存放 API 密钥
• 对团队间的所有工具调用进行治理和审计日志记录
• 为 Agent 提供单个端点，无需连接 N 个 MCP 服务
• 访问控制——限制哪些团队可以使用哪些工具

Docker MCP Gateway

在 Docker MCP Gateway 配置中注册该服务：

{
  "mcpServers": {
    "harness": {
      "command": "npx",
      "args": ["harness-mcp-v2"],
      "env": {
        "HARNESS_API_KEY": "pat.xxx.xxx.xxx"
      }
    }
  }
}

Portkey

将 Harness MCP 服务添加到 Portkey MCP Gateway，以实现企业级治理、成本跟踪和多 LLM 路由：

{
  "mcpServers": {
    "harness": {
      "command": "npx",
      "args": ["harness-mcp-v2"],
      "env": {
        "HARNESS_API_KEY": "pat.xxx.xxx.xxx"
      }
    }
  }
}

LiteLLM

添加到 LiteLLM 代理配置：

mcp_servers:
  - name: harness
    command: npx
    args:
      - harness-mcp-v2
    env:
      HARNESS_API_KEY: "pat.xxx.xxx.xxx"

Envoy AI Gateway

该服务通过 HTTP 传输与 Envoy AI Gateway 的 MCP 支持兼容：

# Start the server in HTTP mode
HARNESS_API_KEY=pat.xxx.xxx.xxx npx harness-mcp-v2 http --port 8080

然后配置 Envoy，将 http://localhost:8080/mcp 作为上游 MCP 后端进行路由。

Kong

使用 Kong 的 AI MCP Proxy 插件，通过现有 Kong 网关基础设施公开 Harness MCP 服务。

其他网关

任何支持 MCP 规范的网关（Microsoft MCP Gateway、IBM ContextForge、Cloudflare Workers 等）都可以代理此服务。对于基于 stdio 的网关，请使用默认传输方式。对于基于 HTTP 的网关，请使用 http 传输方式启动服务，并将网关指向 /mcp 端点。

Docker

将服务构建并运行于 Docker 容器中：

# Build the image
pnpm docker:build

# Run with your .env file
pnpm docker:run

# Or run directly with env vars
docker run --rm -p 3000:3000 \
  -e HARNESS_API_KEY=pat.xxx.xxx.xxx \
  -e HARNESS_ACCOUNT_ID=your-account-id \
  harness-mcp-server

该容器默认以 HTTP 模式在端口 3000 上运行，并内置健康检查。

Kubernetes

使用提供的清单部署到 Kubernetes 集群：

# 1. Edit the Secret with your real credentials
#    k8s/secret.yaml — replace HARNESS_API_KEY and HARNESS_ACCOUNT_ID

# 2. Apply all manifests
kubectl apply -f k8s/

# 3. Verify the deployment
kubectl -n harness-mcp get pods

# 4. Port-forward for local testing
kubectl -n harness-mcp port-forward svc/harness-mcp-server 3000:80
curl http://localhost:3000/health

该部署运行 2 个副本，配有就绪/存活探针、资源限制和非 root 安全上下文。Service 在内部公开端口 80（指向容器端口 3000）。

配置

如果项目根目录中存在 .env 文件，服务会自动加载其中的环境变量。将 .env.example 复制为 .env，并填写相应的值。也可以通过 shell 或 MCP 客户端配置设置环境变量。

变量	必需	默认值	描述
HARNESS_MCP_MODE	否	single-user	部署模式：single-user、multi-user、oauth（直接使用 HarnessID 令牌），或 oauth-proxy（将上游身份提供商令牌交换为每位用户各自的 HarnessID 令牌）
HARNESS_API_KEY	是*	--	Harness 个人访问令牌或服务账户令牌。在 single-user 模式下必需。在 multi-user、oauth 或 oauth-proxy 模式下不得设置；这些模式下，每个会话都会携带自己的凭据
HARNESS_ACCOUNT_ID	否	(来自 PAT/SAT)	Harness 账户标识符。在 single-user 模式下会从 PAT/SAT 令牌自动提取；如果 API 密钥中未包含账户 ID，multi-user 会话可以通过 x-harness-account-id 提供自己的账户 ID
HARNESS_BASE_URL	否	https://app.harness.io（oauth 和 oauth-proxy 模式下为 https://mcp.harness.io/cli）	Harness API/UI 基础 URL。oauth 和 oauth-proxy 模式默认通过托管的 MCP /cli 代理路由；其他模式直接使用 Harness SaaS API
HARNESS_MCP_OAUTH_ISSUER	否	https://id.harness.io/idp/realms/HarnessIDP	与访问令牌 iss 声明进行精确匹配的 HarnessID 颁发者
HARNESS_MCP_OAUTH_RESOURCE	否	https://mcp.harness.io/mcp	在 RFC 9728 中发布为资源标识符的规范公共 MCP URL
HARNESS_MCP_OAUTH_JWKS_URI	否	<issuer>/protocol/openid-connect/certs	用于验证 RS256 访问令牌签名的 HarnessID JWKS 端点
HARNESS_MCP_OAUTH_CLIENT_ID	否	mcp-client	访问令牌必须颁发给的 HarnessID 客户端；通过令牌的 azp 声明进行检查
HARNESS_MCP_OAUTH_ACCOUNT_CLAIM	否	account_id	携带 Harness 账户 ID 的访问令牌声明，由 HarnessID organization 作用域填充
HARNESS_MCP_OAUTH_SCOPES	否	openid profile email organization	在 RFC 9728 受保护资源元数据中公布的、以空格分隔的作用域
HARNESS_MCP_OAUTH_CLIENT_SECRET	是*	--	Harness ID 团队签发的机密 HarnessID 客户端密钥；仅在 oauth-proxy 模式下必需
HARNESS_MCP_OAUTH_EXTERNAL_SUB_CLAIM	否	external_sub	在关联期间与上游主题或上游电子邮件进行匹配的 HarnessID 令牌声明
HARNESS_MCP_OAUTH_PROXY_GRANT	否	refresh	oauth-proxy 模式下后续请求使用的授权类型：refresh 或 jwt-bearer
HARNESS_MCP_OAUTH_PROXY_PUBLIC_URL	是*	--	OAuth 中介的公共来源 URL。oauth-proxy 模式下必需，且必须与 HARNESS_MCP_OAUTH_RESOURCE 具有相同的来源
HARNESS_MCP_OAUTH_PROXY_VAULT_MODE	否	file	file 将加密保险库存储在单个 Pod 的本地磁盘上。redis 在多个 Pod 之间共享刷新令牌和登录状态
HARNESS_MCP_OAUTH_PROXY_VAULT_PATH	否	.harness-mcp/oauth-proxy-vault.enc	当保险库模式为 file 时使用的加密 HarnessID 令牌和登录状态文件
HARNESS_MCP_OAUTH_PROXY_VAULT_KEY	是*	--	oauth-proxy 模式下必需的 Base64 编码 32 字节 AES 密钥
HARNESS_MCP_OAUTH_PROXY_REDIS_URL	是*	--	保险库模式为 redis 时必需的 rediss:// URL。redis:// 需要设置 HARNESS_ALLOW_HTTP=true。Redis 6.2 或更高版本
HARNESS_MCP_OAUTH_PROXY_REDIS_KEY_PREFIX	否	harness-mcp:oauth	Redis 中 OAuth 保险库密钥的前缀
HARNESS_MCP_UPSTREAM_ISSUER	是*	--	oauth-proxy 模式下必需的上游令牌颁发者精确值
HARNESS_MCP_UPSTREAM_AUDIENCE	是*	--	oauth-proxy 模式下必需的上游令牌受众精确值
HARNESS_MCP_UPSTREAM_JWKS_URI	否	<upstream issuer>/v1/keys	上游 RS256 JWKS 端点
HARNESS_MCP_UPSTREAM_SCOPES	否	openid profile email offline_access	内嵌中介请求并向 MCP 客户端公布的作用域
HARNESS_MCP_UPSTREAM_OAUTH_CLIENT_ID	是*	--	内嵌中介使用的机密上游 OAuth 客户端
HARNESS_MCP_UPSTREAM_OAUTH_CLIENT_SECRET	是*	--	仅由服务端使用的上游 OAuth 客户端密钥
HARNESS_MCP_UPSTREAM_DISCOVERY_URI	否	<upstream issuer>/.well-known/openid-configuration	上游 OIDC 发现端点
HARNESS_MCP_UPSTREAM_EMAIL_DOMAINS	否	--	以逗号分隔的域名。通过电子邮件关联要求 email_verified=true，且域名必须在此列表中。列表为空时不会通过电子邮件关联
HARNESS_MCP_BROKER_ISSUER	否	OAuth 代理公共 URL	MCP 客户端发现的授权服务器颁发者
HARNESS_MCP_BROKER_CLIENT_ID	否	cursor-harness-mcp	公共 OAuth 客户端 ID。只要 MCP 客户端配置了相同的值，任何名称都可以
HARNESS_MCP_BROKER_REDIRECT_URIS	否	(空)	以逗号分隔的重定向 URI。为空时拒绝所有回调。* 仅允许环回 http/https。自定义方案必须逐一准确列出
HARNESS_MCP_BROKER_CODE_TTL_MS	否	60000	签发给 MCP 客户端的一次性授权码的有效期
HARNESS_MCP_BROKER_TRANSACTION_TTL_MS	否	600000	链式浏览器授权事务的最长有效期
HARNESS_FME_API_KEY	否	--	可选的单用户/自托管 FME/Split Admin 凭据，仅用于 旧版（workspace_id）模式下的 fme_ 资源。OAuth 模式下无法使用旧版 FME，因此绝不会将 HarnessID 令牌发送到 api.split.io；请改用 Harness 原生的 org_id+project_id 作用域。在 multi-user、oauth 或 oauth-proxy 模式下不得设置
HARNESS_FME_BASE_URL	否	https://api.split.io	仅用于 旧版（workspace_id）模式下 fme_ 资源的 Split/FME Admin API 基础 URL。本地开发使用 HTTP URL 时需要设置 HARNESS_ALLOW_HTTP=true。Harness 原生（org_id+project_id）模式会忽略此项，改用标准的 HARNESS_API_KEY/HARNESS_BASE_URL
HARNESS_ORG	否	--	组织 ID。当每次工具调用未指定 org_id 时使用。如果省略，则必须显式提供 org_id。Agent 也可以通过 harness_list(resource_type="organization") 动态发现组织
HARNESS_PROJECT	否	--	项目 ID。当每次工具调用未指定 project_id 时使用。Agent 也可以通过 harness_list(resource_type="project") 动态发现项目
HARNESS_API_TIMEOUT_MS	否	30000	HTTP 请求超时时间，单位为毫秒
HARNESS_MAX_RETRIES	否	3	暂时性故障（429、5xx）的重试次数
HARNESS_MAX_BODY_SIZE_MB	否	10	http 传输的 HTTP 请求正文最大大小，单位为 MB
HARNESS_RATE_LIMIT_RPS	否	10	客户端对 Harness API 的请求节流速率（每秒请求数）
LOG_LEVEL	否	info	日志详细程度：debug、info、warn、error
HARNESS_TOOLSETS	否	(默认值)	以逗号分隔的工具集列表。留空时加载默认工具集。支持使用 +name 显式包含可选工具集，以及使用 -name 移除默认工具集（参见工具集筛选）
HARNESS_READ_ONLY	否	false	阻止所有变更操作（创建、更新、删除、执行）。仅允许列表和获取操作。适用于共享/演示环境
HARNESS_SCHEMA_MODE	否	compact	compact（默认）或 full。Compact 模式会将每个工具的资源类型枚举替换为普通字符串，并缩短字段说明，使发送给模型的工具列表缩短约一半（参见 docs/schema-budget.md）。通过 harness_describe 发现类型。设置为 full 可内联所有资源类型。
HARNESS_AUTO_APPROVE_RISK	否	none	自主工作流的基于风险的自动批准阈值。风险等级低于或等于此阈值的操作无需确认即可继续。取值：none、low_write、medium_write、high_write、all。参见征询
HARNESS_SKIP_ELICITATION	否	false	已弃用 — 请改用 HARNESS_AUTO_APPROVE_RISK=all。保留此项以向后兼容
HARNESS_ALLOW_HTTP	否	false	允许使用非 HTTPS 的 HARNESS_BASE_URL。默认情况下，服务会强制使用 HTTPS 以确保安全。仅在本地开发时连接非 TLS 的 Harness 实例，才设置为 true
HARNESS_PIPELINE_VERSION	否	0	（Alpha） Pipeline YAML 版本。0 加载 pipeline 资源类型并排除 pipeline_v1；1 加载 pipeline_v1 并排除 pipeline。HTTP 会话可在初始化时通过 x-harness-pipeline-version: 0 或 1 覆盖此值
HARNESS_MCP_ALLOWED_HOSTS	否	--	HTTP 传输 Host 标头验证允许的主机名，以逗号分隔。本地环回绑定默认允许 mcp.harness.io；在此处添加代理/自定义域名
HARNESS_MCP_AUTH_TOKEN	否	--	设置后，访问 /mcp HTTP 路由必须提供静态 Bearer 令牌。对于非环回的 single-user 和 multi-user 绑定，默认必需。在 oauth 模式下必须取消设置
HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP	否	false	显式允许在非环回绑定上使用未经身份验证的 HTTP 传输。仅可在另一个已通过身份验证的控制措施之后使用
HARNESS_MCP_TRUST_PROXY	否	0	信任用于解析客户端 IP 的反向代理/负载均衡器跳数（Express trust proxy）。设置为服务前方的代理数量，以便每 IP 限流使用真实客户端，而不是代理套接字对端
HARNESS_MCP_LOG_FILE	否	~/.claude/harness-mcp.log	当 stderr 可能无法使用时，用于记录 stdio 断开连接/崩溃诊断信息的文件
HARNESS_LOG_UNSAFE_BODIES	否	false	在日志中包含原始请求/响应正文。默认关闭，因为正文可能包含机密；仅在本地调试时启用
HARNESS_AUDIT_FILE	否	--	将审计事件追加到以换行符分隔的 JSON 文件中，以便在本地持久收集
HARNESS_AUDIT_WEBHOOK_URL	否	--	接收批量审计事件的 HTTPS 端点。本地开发使用 HTTP URL 时需要设置 HARNESS_ALLOW_HTTP=true
HARNESS_AUDIT_WEBHOOK_TOKEN	否	--	发送至审计 Webhook 的可选 Bearer 令牌
HARNESS_AUDIT_WEBHOOK_BATCH_SIZE	否	10	刷新 Webhook 前要批量处理的审计事件数量
HARNESS_AUDIT_WEBHOOK_FLUSH_MS	否	5000	刷新 Webhook 前保留审计事件的最长时间
OTEL_EXPORTER_OTLP_ENDPOINT	否	--	安装可选的 OpenTelemetry 软件包后，启用 OpenTelemetry 审计 Span
HARNESS_SEARCH_PROVIDER	否	local	语义搜索后端：local（进程内 ONNX 嵌入，默认）、remote（通过 HTTP 使用外部搜索服务，multi-user 模式必需），或 none（禁用语义搜索，仅回退到关键词 scatter-gather）。在隔离网络环境中，或不希望在启动时加载模型时，使用 none
HARNESS_SEARCH_SERVICE_URL	否	--	HARNESS_SEARCH_PROVIDER=remote 时远程搜索服务的基础 URL（例如 http://search-svc:8080）。使用 remote 提供程序时必需
HARNESS_SEARCH_SERVICE_HEADERS	否	--	随每个请求发送到远程搜索服务的标头 JSON 对象。支持任何身份验证方案：{"Authorization":"Bearer tok"}、{"x-api-key":"key"}，或多个内部服务间标头
HARNESS_HF_CACHE_DIR	否	/tmp/hf-cache	local 搜索提供程序使用的 @huggingface/transformers 模型缓存目录。Docker 镜像会预先将模型烘焙到 /app/.cache/hf，以避免运行时下载。生产部署时将其设置为持久卷路径
HARNESS_DIAGNOSE_LOG_FETCH_CONCURRENCY	否	3	harness_diagnose 为失败步骤获取日志时发起的日志 Blob 下载最大并发数。仅当诊断延迟主要由日志获取耗时造成，且 Pod 有足够内存余量时才增加

语义搜索

harness_search 使用语义路由，在将请求分发到 Harness 之前缩小分散-收集 API 调用的范围。共有三种搜索提供方：

提供方	使用场景
local（默认）	单用户 stdio 模式。通过 @huggingface/transformers 在进程内运行 all-MiniLM-L6-v2。首次使用时下载约 23 MB 的模型；后续启动会使用缓存。
remote	多用户 HTTP 模式（由 Harness 托管）。将嵌入和检索工作委托给外部搜索服务。通过 tenant_id 强制执行租户隔离——静态知识/文档使用 global，每个账户的实体数据使用账户 ID。
none	完全禁用语义搜索；改为对所有资源类型进行关键词分散-收集搜索。

远程提供方配置：

HARNESS_SEARCH_PROVIDER=remote
HARNESS_SEARCH_SERVICE_URL=http://search-svc:8080

# Auth — any scheme via HARNESS_SEARCH_SERVICE_HEADERS (JSON object):
HARNESS_SEARCH_SERVICE_HEADERS='{"Authorization":"Bearer <token>"}'   # standard bearer
HARNESS_SEARCH_SERVICE_HEADERS='{"x-api-key":"<key>"}'               # API key header
HARNESS_SEARCH_SERVICE_HEADERS='{"x-harness-token":"<svc-token>"}'   # internal service-to-service
# Multiple headers (e.g. service mesh + tenant routing):
HARNESS_SEARCH_SERVICE_HEADERS='{"x-harness-token":"<tok>","x-tenant":"<id>"}'
# No auth (service mesh / mTLS handles it):
# omit HARNESS_SEARCH_SERVICE_HEADERS entirely

使用随附的存根服务在本地测试远程提供方（无需外部依赖）：

# 1. Create a venv and install FastAPI
python3 -m venv .venv-stub
.venv-stub/bin/pip install fastapi uvicorn

# 2. Start the stub (in-memory, cosine similarity, corpus + tenant filtering)
.venv-stub/bin/uvicorn stub-search-service:app --port 8082

# 3. Build the MCP server
pnpm build

# 4. Run the integration smoke test
node test-remote-provider.mjs
# Expected output:
#   available: true
#   indexed 2 docs
#   entity search results: pipeline:ts-test score=... corpus=entities
#   knowledge search results: schema:trigger score=...
#   all-corpus search results: (merged, sorted by score)
#   isolation check (other-acct, should be empty): PASS

# 5. Tear down
kill $(lsof -ti :8082)

存根（stub-search-service.py）实现了与生产搜索服务相同的 /v1/health、/v1/ingest 和 /v1/search 接口。它使用简单的字符袋嵌入，因此无需下载模型——结果在语义上看似合理，但达不到生产环境的质量。

HTTPS 强制要求

默认情况下，HARNESS_BASE_URL 必须使用 HTTPS。如果设置了非 HTTPS URL（例如 http://localhost:8080），服务将拒绝启动，并显示：

HARNESS_BASE_URL must use HTTPS (got "http://..."). If you need HTTP for local development, set HARNESS_ALLOW_HTTP=true.

审计日志

配置审计接收器后，所有通过注册表分发的 Harness API 操作（list、get、create、update、delete 和 execute）都会生成结构化审计事件。存在确认上下文时，变更事件会包含由征询或自动批准所采用的确认路径；读取事件目前不包含确认元数据。绕过注册表的本地元数据和架构发现工具（例如 harness_describe 和 harness_schema）不属于此审计流。默认会注册一个 stderr 接收器，但它会经过常规日志记录器并遵循 LOG_LEVEL；如需持久化收集审计信息，请配置文件或 Webhook 接收器：

• HARNESS_AUDIT_FILE 会追加以换行符分隔的 JSON 事件，供本地收集。
• HARNESS_AUDIT_WEBHOOK_URL 会将 { "events": [...] } 批次发送到 HTTPS Webhook；也可以配置 HARNESS_AUDIT_WEBHOOK_TOKEN。失败的批次会重新入队列；队列容量有限，最终会丢弃这些批次并发出警告，而不会阻塞工具执行。
• 安装可选的 OpenTelemetry 对等依赖后，OTEL_EXPORTER_OTLP_ENDPOINT 会启用审计 span。如果已注册 tracer provider，接收器会复用该 provider；否则会初始化独立的 OTLP exporter。

每个事件都包含工具名称、资源类型、操作、标识符、时间戳、风险、结果、HTTP 方法/路径、耗时，以及适用时的确认方式。审计接收器属于尽力而为的遥测机制；传递问题只会记录日志，不会重放或更改底层 Harness API 操作。有关 OTel 设置详情和 span 属性，请参阅 specs/005-otel-audit-sink.md。

工具参考

该服务提供 11 个 MCP 工具。大多数 API 工具都接受可选的 org_id 和 project_id 覆盖值——如果省略，则回退到 HARNESS_ORG 和 HARNESS_PROJECT。harness_describe 仅提供本地元数据，不使用组织/项目范围。

URL 支持： 大多数面向 API 的工具都接受 url 参数——粘贴 Harness UI URL 后，服务会自动提取组织、项目、资源类型、资源 ID、流水线 ID 和执行 ID。harness_describe 不接受 url。

范围支持： 具有账户/组织/项目变体的资源类型会在 harness_describe 中公开 supportedScopes。需要指定级别时，请传入 resource_scope：

• resource_scope: "account" 仅发送 accountIdentifier。
• resource_scope: "org" 发送 accountIdentifier 和 orgIdentifier。
• resource_scope: "project" 发送账户、组织和项目标识符。 当前支持的多范围资源包括 connector、service、environment、infrastructure、secret、file_store、template、policy 和 policy_set。如果省略 resource_scope，注册表会使用资源的默认范围和已配置的默认值，但标记为可选范围的资源可以省略 org/project，除非显式传入这些参数。Harness URL 也可以在路径包含账户级或项目级上下文时自动设置范围。

结构化输出： 每个工具都声明了 MCP outputSchema。harness_list 会将类似列表的 Harness 响应规范化为对象形状的结构化内容，以便严格客户端进行验证：顶层数组会变为 { "items": [...], "total": <count>, "page": <page> }；必要时，content、data、body、objects 或 features 等常见包装键会提升为 items。文本响应仍包含返回给所有客户端的精简 JSON 载荷。

工具	描述
harness_describe	发现可用的资源类型、操作和字段。不调用 API — 返回本地注册表元数据。
harness_schema	获取用于创建或更新资源的精确 YAML/JSON Schema 定义和示例。Pipeline/template Schema 已打包；connector、environment、service、secret 和 infrastructure Schema 是范围感知的实体 Schema，从打包的快照或 NG /yaml-schema 获取；release_process 和 release_activity Schema 从 RMG /api/yamlSchema 实时获取。支持通过 path 深入查看。
harness_list	列出指定类型的资源，支持筛选、搜索和分页。
harness_get	根据标识符获取单个资源。
harness_create	创建新资源。支持内联 Pipeline 和远程（由 Git 支持的）Pipeline。通过 elicitation 请求用户确认。
harness_update	更新现有资源。支持内联 Pipeline 和远程（由 Git 支持的）Pipeline。通过 elicitation 请求用户确认。
harness_delete	删除资源。通过 elicitation 请求用户确认。具有破坏性。
harness_execute	对资源执行操作（运行/重试 Pipeline、从 Git 导入 Pipeline、切换标志、同步应用）。通过 elicitation 请求用户确认。运行 Pipeline 时，请使用下方的运行时输入工作流（支持 branch/tag/pr_number/commit_sha 简写扩展）。
harness_search	使用单个查询跨 Harness 资源类型进行搜索。使用语义路由（本地 all-MiniLM-L6-v2 ONNX 嵌入，384 维）根据启动时建立索引的 knowledge 语料库预测相关资源类型 — 通常会在 scatter-gather 前将范围从约 163 种类型缩小到 1–8 种。语义置信度较低时，会回退到完整的关键词 scatter-gather。触发路由时，响应包含 semantic_routed 和 types_skipped。如何让新资源类型可被发现，请参阅 docs/search-guidelines.md。
harness_diagnose	诊断 pipeline、connector、delegate 和 gitops_application 资源（别名：execution -> pipeline、gitops_app -> gitops_application）。对于 Pipeline，返回阶段/步骤的耗时和故障详情；对于 connector、delegate 和 GitOps 应用，返回有针对性的运行状况和故障排查信号。
harness_status	获取实时项目健康仪表板 — 包含近期执行情况、故障率和深层链接。

Schema 查询工作流

在创建或更新由 YAML 支持的资源前，先使用 harness_schema，以便 Agent 复制准确的字段名称和约束，而不是根据描述猜测。

• 捆绑的 Schema 包括 pipeline、template、trigger、pipeline_v1、template_v1、inputSet_v1、overlayInputSet_v1 和 agent-pipeline。
• 实体 Schema 包括 connector、environment、service、secret 和 infrastructure。这些 Schema 会识别作用域（account、org 或 project），并在所选作用域要求时需要提供 org_id/project_id。
• Release Management 定义（release_process、release_activity）会从 RMG /api/yamlSchema 获取实时 JSON Schema（不随工具捆绑）。将作用域设为 org 或 project 时，请传入 scope、org_id 和 project_id。
• 当随附的实体快照与运行时账号匹配时，会优先使用这些快照；否则工具会回退到 Harness NG /yaml-schema API 并缓存结果。
• 省略 path 可获取字段/部分摘要，然后传入以点分隔的 path 来检查嵌套定义。

示例：

{ "resource_type": "pipeline", "path": "pipeline.stages" }

{
  "resource_type": "connector",
  "scope": "project",
  "org_id": "default",
  "project_id": "payments"
}

当 Harness 实体 YAML Schema 发生变化时，维护者可以使用 pnpm sync-entity-schemas 刷新随附的实体快照。

工具示例

发现可用资源：

{ "resource_type": "pipeline" }

列出账号中的组织：

{ "resource_type": "organization" }

列出组织中的项目：

{ "resource_type": "project", "org_id": "default" }

列出项目中的流水线：

{ "resource_type": "pipeline", "search_term": "deploy", "size": 10 }

获取指定服务：

{ "resource_type": "service", "resource_id": "my-service-id" }

运行流水线：

{
  "resource_type": "pipeline",
  "action": "run",
  "resource_id": "my-pipeline",
  "inputs": { "tag": "v1.2.3" },
  "wait": true
}

切换功能标志：

{
  "resource_type": "feature_flag",
  "action": "toggle",
  "resource_id": "new_checkout_flow",
  "enable": true,
  "environment": "production"
}

搜索所有资源类型：

{ "query": "payment-service" }

按 ID 诊断一次执行（摘要模式 — 默认）：

{ "execution_id": "abc123XYZ" }

通过 Harness URL 进行诊断：

{ "url": "https://app.harness.io/ng/account/.../pipelines/myPipeline/executions/abc123XYZ/pipeline" }

诊断连接器的连通性：

{ "resource_type": "connector", "resource_id": "my_github_connector" }

诊断 Delegate 的运行状况：

{ "resource_type": "delegate", "resource_id": "delegate-us-east-1" }

诊断 GitOps 应用（含选项）：

{
  "resource_type": "gitops_application",
  "resource_id": "checkout-app",
  "options": { "agent_id": "gitops-agent-1" }
}

获取流水线的最新执行报告：

{ "pipeline_id": "my-pipeline" }

完整诊断模式，包含 YAML 和失败步骤日志：

{ "execution_id": "abc123XYZ", "summary": false }

启用日志的摘要模式（兼顾两者）：

{ "execution_id": "abc123XYZ", "include_logs": true }

获取项目健康状态：

{ "org_id": "default", "project_id": "my-project", "limit": 5 }

按迁移类型筛选并列出数据库 Schema：

{ "resource_type": "database_schema", "migration_type": "Liquibase" }

列出某个 Schema 的数据库实例：

{ "resource_type": "database_instance", "dbschema_id": "my_schema" }

获取为某个 Schema 和实例解析出的 LLM 编写流水线：

{ "resource_type": "database_llm_authoring_pipeline", "resource_id": "my_schema", "dbinstance_id": "prod_db" }

列出 Schema 实例的快照对象名称（例如表）：

{
  "resource_type": "database_snapshot_object",
  "dbschema_id": "my_schema",
  "dbinstance_id": "prod_db",
  "object_type": "Table"
}

获取指定名称对象的完整快照元数据：

{
  "resource_type": "database_snapshot_object",
  "resource_id": "prod_db",
  "params": {
    "dbschema_id": "my_schema",
    "object_type": "Table",
    "object_names": ["users", "orders"]
  }
}

Pipeline 运行工作流（推荐）

对于 v0 流水线，请按以下顺序操作，以减少执行时输入错误：

1. 发现必需的运行时输入

• harness_get(resource_type="runtime_input_template", resource_id="<pipeline_id>")
• 返回的模板会显示需要提供值的 <+input> 占位符。

2. 选择输入策略

• **简单变量：**传入扁平的键值对 inputs（例如 {"branch":"main","env":"prod"}）。

• **复杂／结构化输入：**使用 input_set_ids（CI 代码库／构建块和嵌套模板输入最适合通过这种方式处理）。

• CI 代码库的简写键（仅限流水线运行）：

  简写键	展开后的结构
  branch	build.type=branch，build.spec.branch=<value>
  tag	build.type=tag，build.spec.tag=<value>
  pr_number	build.type=PR，build.spec.number=<value>
  commit_sha	build.type=commitSha，build.spec.commitSha=<value>

• **限制：**如果 inputs.build 已存在，则跳过简写展开（显式指定的 build 优先）。

3. 执行运行

• harness_execute(resource_type="pipeline", action="run", resource_id="<pipeline_id>", ...)

• 对于 YAML 应从非默认分支加载的 Git 托管流水线，请传入 params.pipeline_branch（发送给 Harness 时为 branch）。此显式定义选择器优先于 params.branch 别名。inputs.branch 则独立选择 CI 代码库分支：

  {
    "resource_type": "pipeline",
    "action": "run",
    "resource_id": "deploy_app",
    "params": { "pipeline_branch": "feature/new-stage" },
    "inputs": { "branch": "main" },
    "wait": true
  }
  

4. 可选：组合使用

• 使用 input_set_ids 设置基础结构，再通过 inputs 设置简单的覆盖值。

对于 v1 流水线：

1. 获取 harness_get(resource_type="runtime_input_template_v1", resource_id="<pipeline_id>")。 对于 Git 托管流水线，请通过 params 传入 branch_name、connector_ref 和 repo_name。
2. 将每个返回的 inputs[].details.name 用作 harness_execute.inputs 中的顶层键。
3. 运行 harness_execute(resource_type="pipeline_v1", action="run", resource_id="<pipeline_id>", inputs={...})。 服务会将这些值封装在 YAML 根节点 inputs: 下，并发送 API 的 inputs_yaml 请求体。

如果必需字段尚未解析，工具会返回预检错误，其中包含预期键和建议的输入集。你可以使用 harness_describe(resource_type="pipeline")（executeActions.run.inputShorthands）查看可用的简写映射。

动态流水线执行

当 Agent 或外部系统在运行时生成完整的 v0 流水线 YAML，并需要针对现有 Harness 流水线外壳运行该 YAML 时，请使用 pipeline_dynamic_execution.run。这并非普通 pipeline.run 的替代方案：已保存的 v0 流水线必须已存在，账户级和流水线级的 Allow Dynamic Execution 必须已启用，并且调用方需要对该流水线拥有 Edit 和 Execute 权限。

{
  "resource_type": "pipeline_dynamic_execution",
  "action": "run",
  "resource_id": "deploy_app",
  "body": {
    "yaml": "pipeline:\n  identifier: deploy_app\n  name: Deploy App\n  stages: []"
  },
  "params": {
    "module_type": "CD",
    "notes": "agent-generated dynamic run",
    "notify_only_user": true
  }
}

限制：

• body 必须是包含 yaml 字段的对象。公开的 harness_execute 架构会拒绝原始字符串形式的 body。
• body.yaml 可以是 YAML 字符串或 JSON 流水线对象；发送请求前会将 JSON 序列化为 YAML。
• 此 API 不会解析运行时 <+input> 占位符。请提交已完全解析的 YAML。
• 动态执行端点不支持输入集、选择性阶段执行、重试和触发器。
• 此操作属于 high_write，并使用常规确认／自动审批流程。响应会将 API 信封映射为 { "execution_id": "...", "status": "..." }，并在范围数据可用时包含 openInHarness 执行链接。

如果 Harness 拒绝运行并提示未启用，请检查账户级 Allow Dynamic Execution 设置，以及 Pipeline -> Advanced Options -> Dynamic Execution Settings 下的流水线级开关。

执行输入取证

运行后，请使用 execution_inputs 检查生成特定执行的合并输入 YAML。当故障取决于输入集合并、基于 Git 的输入集分支，或仅凭执行页面难以还原的触发器／运行时值时，此功能很有用。

{
  "resource_type": "execution_inputs",
  "resource_id": "PLAN_EXECUTION_ID",
  "params": {
    "resolve_expressions": true,
    "resolve_expressions_type": "RESOLVE_ALL_EXPRESSIONS"
  }
}

get 响应映射为：

• executionId - 来自 resource_id 的计划执行 ID。
• inputSetYaml - 此次运行使用的合并后运行时输入 YAML，或 null。
• inputSetTemplateYaml - 执行时的输入模板，或 null。
• resolvedYaml - 当 resolve_expressions=true 时返回解析表达式后的 YAML，否则通常为 null。
• inputSetDetails - 参与此次执行的已保存输入集，格式为 { identifier, name }。
• inputSetBranchName - 基于 Git 的输入集的源分支，或 null。

execution_inputs 仅支持 get，且属于 read-risk。如果省略 resolve_expressions，服务器会省略 API 查询参数，并由 Harness 使用默认的 UNKNOWN 解析模式。

流水线执行等待模式

对于 pipeline.run、pipeline.retry 和 pipeline_v1.run，传入 wait: true，让服务器持续轮询，直到执行到达终止状态。这样，只需一次工具调用即可启动流水线并检查状态，无需客户端或 LLM 执行轮询循环。

{
  "resource_type": "pipeline",
  "action": "run",
  "resource_id": "deploy_app",
  "inputs": { "branch": "main" },
  "wait": true,
  "wait_timeout_seconds": 900,
  "wait_poll_interval_seconds": 5
}

等待模式行为：

• 默认超时时间为 600 秒；允许范围为 10 秒至 7200 秒。
• 初始轮询间隔默认为 3 秒，之后以 1.5 倍递增，最长为 30 秒。
• 执行成功或失败时，响应会包含 execution_id、execution_status、execution_terminal、execution_elapsed_ms 和 execution_poll_count 等字段。
• 如果触发超时，原始触发仍已成功；响应会包含 execution_timed_out: true 和 _wait.hint，其中包含最后观察到的状态。
• 如果触发成功后轮询失败，响应会包含 _wait.error 和重新检查提示。除非已确认首次执行未在运行，否则不要盲目地重新运行流水线。
• 执行到达失败终止状态时，响应会包含 _diagnose_hint，指向 harness_diagnose(resource_type="execution", options={execution_id: "..."})。

请 AI DevOps Agent 创建流水线：

{
  "prompt": "Create a pipeline that builds a Go app with Docker and deploys to Kubernetes",
  "action": "CREATE_PIPELINE"
}

通过自然语言更新服务：

{
  "prompt": "Add a sidecar container for logging",
  "action": "UPDATE_SERVICE",
  "conversation_id": "prev-conversation-id",
  "context": [{ "type": "yaml", "payload": "<existing service YAML>" }]
}

流水线存储模式

Harness 流水线可以通过三种方式存储：

模式	描述	适用场景
内联	流水线 YAML 存储在 Harness 中	默认方式。设置最简单，无需 Git。
远程（外部 Git）	流水线 YAML 存储在 GitHub、GitLab、Bitbucket 等平台中	使用外部提供商，通过 Git 管理流水线即代码的团队。
远程（Harness Code）	流水线 YAML 存储在 Harness Code 代码库中	使用 Harness 内置 Git 托管的团队。

创建内联流水线（默认）：

// harness_create
{
  "resource_type": "pipeline",
  "body": {
    "yamlPipeline": "pipeline:\n  name: My Pipeline\n  identifier: my_pipeline\n  stages:\n    - stage:\n        name: Build\n        type: CI\n        spec:\n          execution:\n            steps:\n              - step:\n                  type: Run\n                  name: Echo\n                  spec:\n                    command: echo hello"
  }
}

创建远程流水线（外部 Git — 例如 GitHub）：

// harness_create
{
  "resource_type": "pipeline",
  "body": {
    "yamlPipeline": "pipeline:\n  name: Deploy Service\n  identifier: deploy_service\n  stages: []"
  },
  "params": {
    "store_type": "REMOTE",
    "connector_ref": "my_github_connector",
    "repo_name": "my-repo",
    "branch": "main",
    "file_path": ".harness/deploy-service.yaml",
    "commit_msg": "Add deploy pipeline via MCP"
  }
}

创建远程流水线（Harness Code — 无需连接器）：

// harness_create
{
  "resource_type": "pipeline",
  "body": {
    "yamlPipeline": "pipeline:\n  name: Build App\n  identifier: build_app\n  stages: []"
  },
  "params": {
    "store_type": "REMOTE",
    "is_harness_code_repo": true,
    "repo_name": "product-management",
    "branch": "main",
    "file_path": ".harness/build-app.yaml",
    "commit_msg": "Add build pipeline via MCP"
  }
}

更新远程流水线：

// harness_update
{
  "resource_type": "pipeline",
  "resource_id": "deploy_service",
  "body": {
    "yamlPipeline": "pipeline:\n  name: Deploy Service\n  identifier: deploy_service\n  stages:\n    - stage:\n        name: Deploy\n        type: Deployment"
  },
  "params": {
    "store_type": "REMOTE",
    "connector_ref": "my_github_connector",
    "repo_name": "my-repo",
    "branch": "main",
    "file_path": ".harness/deploy-service.yaml",
    "commit_msg": "Update deploy pipeline via MCP",
    "last_object_id": "abc123",
    "last_commit_id": "def456"
  }
}

从外部 Git 仓库导入流水线：

// harness_execute
{
  "resource_type": "pipeline",
  "action": "import",
  "params": {
    "connector_ref": "my_github_connector",
    "repo_name": "my-repo",
    "branch": "main",
    "file_path": ".harness/existing-pipeline.yaml"
  },
  "body": {
    "pipeline_name": "Existing Pipeline",
    "pipeline_description": "Imported from GitHub"
  }
}

从 Harness Code 仓库导入流水线：

// harness_execute
{
  "resource_type": "pipeline",
  "action": "import",
  "params": {
    "is_harness_code_repo": true,
    "repo_name": "product-management",
    "branch": "main",
    "file_path": ".harness/existing-pipeline.yaml"
  },
  "body": {
    "pipeline_name": "Existing Pipeline"
  }
}

创建连接器：

{
  "resource_type": "connector",
  "body": { "connector": { "name": "My Docker Hub", "identifier": "my_docker", "type": "DockerRegistry" } }
}

删除触发器：

{
  "resource_type": "trigger",
  "resource_id": "nightly-trigger",
  "pipeline_id": "my-pipeline"
}

列出流水线的输入集：

{
  "resource_type": "input_set",
  "pipeline_id": "my-pipeline"
}

获取特定输入集：

{
  "resource_type": "input_set",
  "resource_id": "prod-inputs",
  "pipeline_id": "my-pipeline"
}

创建输入集：

{
  "resource_type": "input_set",
  "pipeline_id": "my-pipeline",
  "body": "inputSet:\n  name: Production Inputs\n  identifier: prod_inputs\n  pipeline:\n    identifier: my-pipeline\n    variables:\n      - name: env\n        type: String\n        value: production"
}

更新输入集：

{
  "resource_type": "input_set",
  "resource_id": "prod_inputs",
  "pipeline_id": "my-pipeline",
  "body": "inputSet:\n  name: Production Inputs\n  identifier: prod_inputs\n  pipeline:\n    identifier: my-pipeline\n    variables:\n      - name: env\n        type: String\n        value: production\n      - name: replicas\n        type: String\n        value: \"3\""
}

删除输入集：

{
  "resource_type": "input_set",
  "resource_id": "prod_inputs",
  "pipeline_id": "my-pipeline"
}

资源类型

263 种资源类型，分为 42 个工具集。每种资源类型都支持一部分 CRUD 操作和可选的执行操作。

平台

资源类型	列表	获取	创建	更新	删除	执行操作
organization	x	x	x	x	x
project	x	x	x	x	x

流水线

资源类型	列表	获取	创建	更新	删除	执行操作
pipeline	x	x	x	x	x	run、retry
pipeline_v1 （Alpha）	x	x	x	x	x	run
pipeline_dynamic_execution						run
execution	x	x				interrupt
execution_inputs		x
trigger	x	x	x	x	x
pipeline_summary		x
input_set	x	x	x	x	x
runtime_input_template		x
runtime_input_template_v1		x
pipeline_resolved_yaml		x
approval_instance	x					approve、reject

启用 pipelines 工具集后，即可使用这两种流水线 YAML 资源类型。HARNESS_PIPELINE_VERSION 和 HTTP x-harness-pipeline-version 初始化标头用于选择默认版本偏好；它们不会隐藏另一种版本。

AI Agent

资源类型	列表	获取	创建	更新	删除	执行操作
agent	x	x	x	x	x
agent_run	x

服务

资源类型	列出	获取	创建	更新	删除	执行动作
service	x	x	x	x	x

环境

资源类型	列出	获取	创建	更新	删除	执行动作
environment	x	x	x	x	x	move_configs

连接器

资源类型	列出	获取	创建	更新	删除	执行动作
connector	x	x	x	x	x	test_connection
connector_catalogue	x
llm_model	x

基础设施

资源类型	列出	获取	创建	更新	删除	执行动作
infrastructure	x	x	x	x	x	move_configs

密钥

资源类型	列出	获取	创建	更新	删除	执行动作
secret	x	x

执行日志

资源类型	列出	获取	创建	更新	删除	执行动作
execution_log		x

审计跟踪

资源类型	列出	获取	创建	更新	删除	执行动作
audit_event	x	x

代理

资源类型	列出	获取	创建	更新	删除	执行动作
delegate	x	x
delegate_token	x	x	x		x	revoke, get_delegates

代码仓库

资源类型	列出	获取	创建	更新	删除	执行动作
repository	x	x	x	x
branch	x	x	x		x
commit	x	x	x			diff, diff_stats
file_content	x	x				blame
tag	x		x		x
repo_rule	x	x
space_rule	x	x

创建 commit 会通过 Harness Code API 直接提交一个或多个文件操作，无需克隆。传入 body.title、body.branch 和 body.actions；每个操作可以是 CREATE、UPDATE、DELETE 或 MOVE，且 UPDATE 需要当前 blob SHA。

file_content 的列表操作会返回某个 ref 上的所有路径；获取操作会返回文件或目录内容（省略 path 或传入空值表示仓库根目录；嵌套路径需保留斜杠）。省略 git_ref 可使用仓库默认分支——不要猜测为 main。

制品注册表

资源类型	列出	获取	创建	更新	删除	执行操作
registry	x	x
artifact	x
artifact_version	x
artifact_file	x

文件存储

资源类型	列出	获取	创建	更新	删除	执行操作
file_store	x	x	x	x	x	list_children

file_store 通过通用工具管理 Harness 文件存储中的文件和文件夹。它支持账户、组织和项目范围；传入 resource_scope="account"|"org"|"project"，或粘贴 Harness 文件存储 URL，让服务推导范围和 ID。

常见调用：

# List the account-level File Store.
harness_list(resource_type="file_store", resource_scope="account")

# Create a folder at the current scope root.
harness_create(resource_type="file_store", body={
  name: "scripts",
  type: "FOLDER",
  parent_identifier: "Root"
})

# Upload a UTF-8 script file. Use content_base64 instead for binary data.
harness_create(resource_type="file_store", body={
  name: "deploy.sh",
  type: "FILE",
  parent_identifier: "Root",
  content: "#!/usr/bin/env bash\n./deploy",
  mime_type: "text/x-shellscript",
  file_usage: "SCRIPT"
})

# Rename metadata without replacing file content.
harness_update(resource_type="file_store", resource_id="deploy_script", body={
  name: "deploy-prod.sh",
  type: "FILE",
  parent_identifier: "Root"
})

# List first-level children of a folder. This is a read-risk execute action.
harness_execute(resource_type="file_store", action="list_children",
  resource_id="scripts_folder", params={folder_name: "scripts"})

多部分请求体限制：

• 创建/更新接受 JSON body，然后将其转换为 /ng/api/file-store 所需的 multipart/form-data。
• 必须提供 name、type（FILE 或 FOLDER）和 parent_identifier；仅当目标是所选范围的根目录时，才使用字面值 "Root"。
• 创建 FILE 时，必须且只能提供 content（UTF-8 字符串）或 content_base64（有效的非空 base64）之一。更新 FILE 时，可以省略内容以仅更新元数据，也可以提供一个内容字段来替换内容。
• 创建/更新 FOLDER 时，必须省略 content 和 content_base64。
• 可选的 file_usage 必须是 MANIFEST_FILE、CONFIG 或 SCRIPT；description、mime_type、path 和 tags 等可选标量元数据必须是字符串。
• 上传内容上限为 100 MB。征求确认时，会对 content、content_base64 和 contentBase64 预览进行脱敏。

list_children 接受简写形式（resource_id 加 params.folder_name，或 params.file_store_id/params.folder_identifier 加 params.folder_name），也接受包含 identifier、name 和 type: "FOLDER" 的完整 FileStoreNode body。完整请求体使用 Harness 驼峰命名的 parentIdentifier；简写形式可使用 params.parent_identifier。

模板

资源类型	列出	获取	创建	更新	删除	执行操作
template	x	x	x	x	x

模板操作使用 Harness Template 服务路径（/template/api/templates...）。创建和更新要求在 body.template_yaml 或 body.yaml 中提供完整的模板 YAML 字符串；version_label 用于指定更新/删除的版本，而不提供 version_label 时，删除将移除所有版本。

仪表板

资源类型	列出	获取	创建	更新	删除	执行操作
dashboard	x	x
dashboard_data		x

数据库 DevOps

资源类型	列出	获取	创建	更新	删除	执行操作
database_schema	x	x	x	x	x
database_instance	x	x	x	x	x
database_snapshot_object	x	x
database_llm_authoring_pipeline		x

基础设施即代码管理（IaCM）

IaCM 资源默认启用，且大多限定于项目范围。首先使用 iacm_workspace 查找工作区标识符，然后使用该 workspace_id 查询工作区资源、成本和活动差异。使用 iacm_variable_set 管理账户、组织或项目范围内可复用的变量集。提供程序注册表限定于账户范围。

iacm_module 涵盖账户、组织和项目范围。默认使用账户注册表；每项操作（列表、获取、创建、更新）都会发送相同的 scope_org / scope_project 查询参数，因此创建的模块可在创建时指定的范围内查到。通过 resource_scope="account" | "org" | "project" 以及 org_id/project_id 选择范围。范围限定是可选的：省略 resource_scope 时，只有在显式传入 org_id/project_id 的情况下才会应用它们；不会应用已配置的 HARNESS_ORG/HARNESS_PROJECT 默认值，因此当前项目配置不会悄然将账户模块注册到项目下。模块请求体自身的 org/project 字段用于定位其 Git 连接器，与此可见性范围无关。

iacm_workspace 的创建/更新操作仅返回 { policy_evaluation }——随后使用 harness_get 获取工作区。iacm_variable_set 和 iacm_module 的创建/更新操作会返回资源本身。iacm_provider 的创建操作仅返回 { id }——随后使用 harness_get 获取资源；更新操作仅面向版本（POST/PUT /providers/{id}/version）——没有元数据 PUT。版本写入可能会返回空响应体；HarnessClient 会将其规范化为 { status: "SUCCESS", message: "No content" }。

变量集的更新操作使用 HTTP PUT，并会完整替换集合——始终先执行 harness_get，然后 PUT 完整的目标请求体（更新时必须提供 terraform_variables / environment_variables；省略或置空会清除连接器和变量文件）。模块更新同样使用 PUT——对于可选字段，建议先获取再 PUT。写入操作属于 medium_write，需要确认（通过 elicitation 或 confirm: true）。

Harness 目前将变量集和提供程序注册表 RBAC（iac_variableset_*、iac_providerregistry_*）标记为 Experimental——在 iac-server 启用强制执行之前，访问检查始终允许通过。模块注册表 RBAC（iac_registry_view / iac_registry_edit）为 Active，且可强制执行。MCP 始终原样转发调用方的 PAT/SAT。

资源类型	列表	获取	创建	更新	删除	执行操作
iacm_workspace	x	x	x	x
iacm_variable_set	x	x	x	x
iacm_resource	x
iacm_module	x	x	x	x
iacm_provider	x	x	x	x
iacm_workspace_costs	x
iacm_activity_resource_change	x

典型工作流：

1. 使用 harness_list(resource_type="iacm_workspace", org_id="...", project_id="...") 查找工作区。
2. 使用 harness_create / harness_update 操作 iacm_workspace，从头创建、基于模板（associated_template）创建，或更新现有工作区——响应仅为 { policy_evaluation }。
3. 使用 harness_get(resource_type="iacm_workspace", workspace_id="...") 获取已创建或更新的工作区。
4. 使用 harness_list / harness_create / harness_update 操作 iacm_variable_set（可选提供 resource_scope），管理可复用的 Terraform / 环境变量集——响应为 VariableSet 资源。
5. 使用 harness_list / harness_create / harness_update 操作 iacm_module，管理模块注册表（必须提供 name 和 system；为组织级或项目级模块添加包含 org_id / project_id 的 resource_scope）——响应为模块资源。
6. 使用 harness_list / harness_create / harness_update 操作 iacm_provider，管理账户提供程序注册表（创建时必须提供 body.type；创建时仅返回 { id }——然后调用 harness_get；更新仅创建或更新版本）——版本更新可能返回空成功响应。
7. 使用 harness_list(resource_type="iacm_resource", org_id="...", project_id="...", workspace_id="...") 检查 Terraform 资源、输出和数据源。
8. 使用 harness_list(resource_type="iacm_workspace_costs", org_id="...", project_id="...", workspace_id="...") 查看每次执行的成本条目。
9. 使用 harness_list(resource_type="iacm_activity_resource_change", org_id="...", project_id="...", activity_id="...", workspace_id="...") 检查计划、应用或销毁活动的资源变更前后差异。

IaCM 列表响应中的 page_count 仅表示当前页的数量（iacm_variable_set 除外，该资源不分页）。当 has_more 为 true 时，继续请求下一页（页码从 1 开始）；如需获取总数，请累加各页的数量。

内部开发者门户（IDP）

资源类型	列表	获取	创建	更新	删除	执行操作
idp_entity	x	x
scorecard	x	x
scorecard_check	x	x
scorecard_stats		x
scorecard_check_stats		x
idp_score	x	x
idp_workflow	x					execute
idp_tech_doc	x

拉取请求

资源类型	列出	获取	创建	更新	删除	执行动作
pull_request	x	x	x	x		close、merge
pr_reviewer	x		x			submit_review
pr_comment			x	x	x	resolve、unresolve
pr_check	x
pr_activity	x

使用 harness_execute(resource_type="pull_request", action="close", ...) 执行明确的关闭操作。harness_update 也接受 body.state（open 或 closed），并将状态更改路由到专用的 Harness Code PR 状态端点；请在单独的更新调用中发送标题／描述编辑。

使用 harness_list(resource_type="pr_activity", filters={type: ["comment", "code-comment"]}, ...) 读取 PR 评论。使用 pr_comment 执行评论写入操作。

使用 harness_execute(resource_type="pr_comment", action="resolve", ...) 解决评论讨论串，使用 action="unresolve" 重新打开；这两种操作都不需要正文。comment_id 必须是 pr_activity 中某一行的 id，且该行的 parent_id 为 null；API 会拒绝回复 ID。

发布管理

发布管理（RMG）资源默认启用。定义资源（release_process、release_activity）支持使用 body.yaml 执行 list/get/create/update/delete；在 create/update 前调用 harness_schema(resource_type="release_process"|"release_activity")。执行资源用于监控正在运行的发布 — 大多数 list 操作都需要 release_id（可从 harness_list resource_type=release 获取 UUID，或使用 UI URL 中的 slug，例如 identifier-1.0.0-abc）。将 RMG 发布 URL 粘贴到 harness_list，即可自动填入 release_id。

RMG 调用使用 ${HARNESS_BASE_URL}/gateway/rmg，并通过 Harness-Account 标头指定账户范围。提供 org_id/project_id 时，组织/项目范围通过标头指定。release_execution_phase 仅支持 list — 调用 harness_get 查询阶段输入/输出资源时，请使用每个阶段项目的 identifier 字段作为 params.phase_identifier（不要对 release_execution_phase 本身调用 harness_get）。发布列表的 status 筛选仅应用于当前页；结果可能跨页时，请使用相同的筛选条件继续翻页。

资源类型	List	Get	Create	Update	Delete	执行操作
release_process	x	x	x	x	x
release_activity	x	x	x	x	x
release	x	x
release_execution_phase	x
release_execution_task	x
release_execution_activity	x
release_input		x
release_execution_phase_input		x
release_execution_phase_output		x
release_execution_activity_input		x
release_execution_activity_output		x

典型工作流：

1. 使用 harness_list(resource_type="release_process", org_id="...", project_id="...") 查找编排流程定义。
2. 创建/更新前调用 harness_schema(resource_type="release_process")（或 release_activity）；然后使用 body.yaml 调用 harness_create / harness_update。
3. 使用 harness_list(resource_type="release", org_id="...", project_id="...") 查找活跃或近期的发布（默认回溯 30 天；可选参数为 filters.status、filters.search_term、filters.days_back）。
4. 使用 harness_get(resource_type="release", release_id="...") 获取发布详情。
5. 使用 harness_list(resource_type="release_execution_phase", filters={ release_id: "..." }) 查看阶段状态；查询 release_execution_task 和 release_execution_activity 时也使用相同的 release_id。
6. 根据各资源的文档，使用 release_id 以及 params.phase_identifier / params.activity_identifier / activity_execution_id 调用 harness_get，查询 release_input、release_execution_phase_input、release_execution_phase_output、release_execution_activity_output 或 release_execution_activity_input。

Vibe

默认启用的 vibe 工具集涵盖 Vibe Orchestrator BFF 合约，路径为 ${HARNESS_BASE_URL}/vibe/v1。它使用现有的 Harness 连接和账户标头，不会添加账户／组织／项目查询参数，也不会向请求正文添加作用域字段。团队使用 Harness API 密钥身份验证（PAT/SAT）验证了 Vibe 流程，因此默认会话无需选择启用设置。精选的 OpenAPI 文档说明了 bearer/session 身份验证；服务器的 OAuth 模式会转发当前会话的 bearer 令牌。自动化回归测试会验证这两种标头路径；网关身份验证仍取决于目标环境的配置。

资源类型	列表	获取	创建	更新	删除	执行操作
vibe_project			x			prepare、deploy
vibe_app_lifecycle		x				events

该 API 支持两种输入方式。请保留这些 API 原生请求格式：

编码 Agent 可用的来源	API 流程
GitHub 仓库链接／连接器	使用 resource_type="vibe_project"、body.mode 及特定模式的字段调用 harness_create。合约中提到了 github_link 和 github_connector，但未定义它们的 URL、分支或连接器字段格式；这些字段会原样转发给后端，不会擅自映射。
ZIP 文件	使用应用名称和文件元数据调用 prepare，将字节上传到返回的签名目标，然后调用 deploy。
本地源目录	编码 Agent 在本地将预期的工作区源文件打包为 ZIP，然后按照 ZIP 流程操作。本地路径或对话上下文不是 API 支持的源文件上传方式。

打包目录时，请包含构建所需的源文件、清单、锁文件、配置以及预期的未提交更改。请排除凭据、.git、已安装的依赖项和生成的产物。打包和签名上传必须在可访问文件的位置进行；托管的 MCP 服务无法读取编码 Agent 的本地目录。

对于现有 ZIP，请准备上传：

{
  "resource_type": "vibe_project",
  "action": "prepare",
  "body": {
    "name": "demo-app",
    "file": {
      "path": "app.zip",
      "size_bytes": 12345,
      "content_type": "application/zip"
    }
  }
}

将其传递给 harness_execute。大小必须反映 ZIP 的实际大小；size_bytes、content_type 和 md5 均为可选且可为空。OpenAPI 允许的其他 prepare 字段会保留，以供后端验证。准备操作会返回 projectId、sourceId 和 upload，其中包括每个文件的 uploadUrl、method、headers 和 expiresAt。请使用该签名 URL、方法和标头直接上传文件字节；准确保留 URL，不要在存储请求中添加 Harness 凭据。prepare 操作不会读取或上传本地文件。

上传成功后，请明确部署：

{
  "resource_type": "vibe_project",
  "action": "deploy",
  "resource_id": "<projectId returned by prepare>"
}

对于 JSON 导入，请改用返回的 id。部署也接受 body: {"project_id": "<Vibe app id>"} 或 params.app_id；API 线缆字段为 snake_case 的 project_id，而 prepare 返回的 projectId 为 camelCase。通用工具顶层的 project_id 是 Harness 作用域标识符，绝不会用作 Vibe 应用 ID。导入和 prepare 会创建应用／源文件，但都不会启动部署。写入操作不会自动重试，部署沿用现有的高风险确认策略。 使用 harness_get(resource_type="vibe_app_lifecycle", resource_id="<Vibe app id>") 读取进度。它会保留应用 URL、执行阶段、子步骤、失败信息、日志行和构建分析器详情。events 执行操作接受 resource_id 或 params.app_id，并将 SSE 端点作为有限批次使用：最多 20 个 JSON 事件，或连接后五秒，响应上限为 1 MiB。这些限制由 Vibe 端点决定。连接的 HARNESS_API_TIMEOUT_MS 也会同时限制连接和流的读取；超时会返回超时错误。完成的批次会返回 events 和 stop_reason（end、event_limit 或 duration_limit），并关闭流。初始连接失败或流中断时均不会重试。事件是临时差异，没有文档说明的重放游标；请使用生命周期 get 获取权威快照。只读模式下，两种生命周期读取操作均可用。

功能标志

资源类型	列出	获取	创建	更新	删除	执行操作
fme_workspace	x
fme_environment	x	x	x	x	x
fme_feature_flag	x	x	x	x	x	kill、restore、reallocate、archive、unarchive
fme_feature_flag_definition	x	x	x	x	x	kill、restore、reallocate
fme_rollout_status	x
fme_rule_based_segment	x	x	x		x
fme_rule_based_segment_definition	x			x		enable、disable、change_request
fme_traffic_type	x
fme_identity			x	x
fme_standard_segment	x	x
fme_segment_keys	x			x
fme_segment	x	x	x	x	x
fme_segment_definition	x	x	x	x	x	list_keys、add_keys、remove_keys
fme_metric	x	x	x	x	x
fme_event_type	x	x
fme_experiment	x	x	x	x	x
fme_experiment_settings		x		x	x
fme_experiment_alerting		x		x
fme_experiment_result	x
FME（Split.io）资源 — fme_* 资源支持双模式范围限定：旧版调用传入 workspace_id，并访问 Split.io API（api.split.io）；新版调用同时传入 org_id+project_id，并改为访问 Harness 原生端点（使用标准 HARNESS_API_KEY/HARNESS_BASE_URL，与其他所有 harness_* 资源使用相同的身份验证）。同一次调用同时传入 workspace_id 和 org_id/project_id，或仅传入 org_id 和 project_id 其中之一，都会报错——每次调用请选择一种模式。除非资源标记为仅支持 Harness 原生模式，以下每项操作均可在旧版模式下使用，且行为不变。Harness 原生模式目前覆盖范围较窄：

• fme_workspace — 没有对应的 Harness 原生资源；仅支持旧版模式（用于发现 workspace_id 值）。
• fme_environment — list 支持双模式（传入 workspace_id 或 org_id+project_id）。get/create/update/delete 仅支持 Harness 原生模式（/fme/api/v4/environments）——MCP 从未为这些操作定义 workspace_id 契约。原生列表使用可选的 offset/limit（最大值为 100；harness_list 的 size 会映射到 limit）；信封 {data, limit, offset, totalCount} 会转换为 items/total。原生创建/更新使用 isProduction（也接受别名 production）。原生更新采用 JSON Merge Patch；name 和 isProduction 不可清除。名称最长为 15 个字符。
• fme_feature_flag — 支持双模式，两个分支均已完整接入。Harness 原生模式（org_id+project_id）：list/get/create/delete 访问 /fme/api/v4/feature-flags（create 的请求体包含 name、trafficType，以及可选的 description/tags/owners，符合 CreateFeatureFlagRequest）；update 向 /fme/api/v4/feature-flags/{name} 发送 merge-patch；archive/unarchive 访问 /fme/api/v4/feature-flags/{name}/archive|unarchive（仅接受可选的 comment——不接受 title，符合 ArchiveUnarchiveRequest）；kill/restore/reallocate 访问 /fme/api/v4/feature-flag-definitions/{name}/kill|restore|reallocate，并将 environment_id 作为查询参数（可选的 comment/title，符合 FeatureFlagDefinitionActionRequest）。
• fme_feature_flag_definition — get/create/update 继续支持双模式（传入 workspace_id 或 org_id+project_id）。list/delete/kill/restore/reallocate 仅支持 Harness 原生模式（org_id+project_id）——MCP 从未为这些操作定义 workspace_id 契约。原生列表要求提供 feature_flag_name，并使用 offset/limit（默认值为 100，最大值为 100）；不接受 environment_id。删除和执行操作要求提供 environment_id。kill/restore/reallocate 与 fme_feature_flag 中的操作相同。get/create/update 的请求体与旧版模式相同（包含 treatments、defaultTreatment、defaultRule，以及可选的 rules/baselineTreatment/trafficAllocation/comment），此外 Harness 原生模式还接受可选的 title。原生更新采用 JSON Merge Patch。
• fme_rollout_status — list 支持双模式。传入 org_id+project_id（推荐）或已弃用的 workspace_id。原生分页使用 offset/limit（最大值为 100；harness_list 的 size 会映射到 limit）；结果会转换为 items/total。每项包含 id、name 和可选的 description。
• fme_rule_based_segment —（已弃用 — 请参阅 fme_segment。）所有操作（list/get/create/delete）均不接受 Harness 原生模式 — 请改用 fme_segment；此资源仅支持旧版 workspace_id 契约。
• fme_rule_based_segment_definition —（已弃用 — 请参阅 fme_segment_definition。）所有操作/动作（list/update/enable/disable/change_request）均不接受 Harness 原生模式 — 请改用 fme_segment_definition（该资源没有对应的 enable/disable/change_request 功能）；此资源仅支持旧版 workspace_id/environment_id 契约。
• fme_traffic_type — list 支持双模式。传入 org_id+project_id（首选）或已弃用的 workspace_id。原生分页使用 offset/limit（最大值为 100；harness_list 的 size 映射为 limit）；结果会转换为 items/total。每个项目包含 id 和 name（不含 displayAttributeId）。
• fme_identity — 如果同时传入 org_id+project_id，则尚未实现 create/update；否则按常规旧版调用执行。
• fme_standard_segment — 已弃用。旧版 workspace_id 仍会调用 Split v2。不接受 Harness 原生模式 — 请改用 fme_segment。
• fme_segment_keys — list/update 仍为旧版操作（workspace_id / environment_id+segment_name）。不接受 Harness 原生模式（org_id+project_id）— 请使用 fme_segment_definition 执行 list_keys/add_keys/remove_keys。
• fme_segment — 仅支持原生模式（org_id+project_id）。支持 CRUD。list/get/update/delete 需要 segment_type：STANDARD | LARGE | RULE_BASED。创建请求体：name、trafficType、segmentType；可选字段：description、tags、owners。
• fme_segment_definition — 仅支持原生模式。支持 CRUD，并可执行 list_keys/add_keys/remove_keys。update 仅支持描述。只要仍有键，delete 就会因 hasDependents 失败。
• fme_metric — 仅支持 Harness 原生模式（不支持旧版 workspace_id）。list/get/create/update/delete 已接入 /fme/api/v4/metrics（list 的 harness_list size 映射为 limit）。create 要求提供 spread，尽管后端的 CreateMetricRequest 将其设为可选项（默认值为 PER）——这是仅在 MCP 端实施的更严格契约，因为省略该字段会悄然改变 RATE 指标的语义。update 使用 JSON Merge Patch；不接受不可变的 name/trafficType。delete 会永久硬删除（不支持归档/恢复）— 分类为 destructive。
• fme_event_type — 仅支持 Harness 原生模式（不支持旧版 workspace_id）。只读：list/get 已接入 /fme/api/v4/event-types；id 即事件名称。仅显示过去 30 天内有事件的事件类型；对于不在请求工作区流量类型范围内，或超过 30 天没有活动的事件类型，get 会返回 404。列表筛选条件：name（子字符串）、traffic_type（按 ID 或名称）、offset/limit（harness_list 的 size 映射为 limit）。在 fme_metric 的 baseEventTypes/filterEventType 或 event_type_ids 筛选条件中引用事件类型 ID 前，请先使用此工具查找实际 ID，而不要猜测 ID。
• fme_experiment — 仅支持 Harness 原生模式（不支持旧版 workspace_id）。CRUD 已接入 /fme/api/v4/experiments。list 需要 parent_type（FEATURE_FLAG、AI_CONFIG；CONFIG 会返回 404），如果未传入 status，则默认仅列出 ACTIVE 实验。create 需要 environment_id（查询参数），以及请求体中的 parent/name/startAt/endAt/baselineTreatment/comparisonTreatments；父级必须存在于该环境中。update 使用 JSON Merge Patch；无法更改 parent 和 environment。delete 会永久硬删除 — 分类为 destructive。创建/更新时可选传入 owners：每个条目为 {type: "USER", id or email} 或 {type: "GROUP", identifier}。创建/更新时可选传入 rule（目标规则标签结果的作用范围；创建时若省略则默认为 "default"，更新时设为 null 可清除该值）和 tags（[{name}]；更新时会替换列表，设为 null/[] 可清除）。list 接受 tags 数组筛选条件（匹配包含任一标签名称的实验）；项目包含 tags 和 rule。
• fme_experiment_settings — 单个实验的统计与监控设置（测试类型、显著性阈值、多重比较校正、最小样本量、审查周期、方差缩减）。仅支持 get/update/delete — 与实验为 1:1 关系，不支持 list。get 始终返回已应用的设置（自定义覆盖项或组织默认值）；除非实验本身不存在，否则不会返回 404。update 使用 JSON Merge Patch，并会隐式创建实验级覆盖项。delete 会恢复为组织默认值（幂等）— 即使此操作并非永久删除，也分类为 destructive。
• fme_experiment_alerting — 单个实验是否订阅了显著性回退告警。仅支持 get/update。get 返回 {id, isEnabled}；若不存在告警策略，则返回 isEnabled: false；只有实验本身不存在时才会返回 404。update 使用 JSON Merge Patch，并要求提供布尔值 isEnabled。
• fme_experiment_result — 实验最新计算运行按指标评估的结果。仅支持 list（不支持 get — 结果本身没有标识符）。每个（指标、对照处理）组合在所有指标类别中对应一行。可选筛选条件：metric_ids、comparisons。仅反映最新运行 — 无法访问历史记录。 在单用户／可自托管模式下，旧版模式身份验证使用 HARNESS_FME_API_KEY 中的 Bearer 令牌；如果未设置，则回退到非占位符的 HARNESS_API_KEY。HARNESS_FME_API_KEY 可以是旧版 Split 管理员密钥，也可以是具有 FME 权限的 Harness PAT/SAT；但在 multi-user 模式下会被拒绝，以防共享部署覆盖各会话用户的凭据。用于 Harness 平台 API 的托管 OAuth／服务路由凭据不能对直接的 Split.io 请求进行身份验证。fme_feature_flag 在旧版模式下支持完整生命周期管理：创建（需要 traffic_type_id）、列出、获取、更新元数据、删除，以及执行 kill／恢复／重新分配／归档／取消归档操作。使用 fme_traffic_type 查找流量类型 ID，使用 fme_identity 创建／更新身份属性，使用 fme_standard_segment／fme_segment_keys 查看标准细分并添加成员键。fme_rule_based_segment 提供针对目标细分的 CRUD 操作，而 fme_rule_based_segment_definition 用于管理特定环境的细分规则，并支持启用／禁用及变更请求审批流程。

GitOps

资源类型	列出	获取	创建	更新	删除	执行操作
gitops_agent	x	x
gitops_agent_metrics	x
gitops_argo_project	x
gitops_app_project_mapping	x		x	x	x	import
gitops_autocreate_log	x
gitops_application	x	x				sync
gitops_cluster	x	x
gitops_repository	x	x
gitops_applicationset	x	x
gitops_repo_credential	x	x
gitops_app_event	x
gitops_pod_log		x
gitops_managed_resource	x
gitops_resource_action	x
gitops_dashboard		x
gitops_app_resource_tree		x
gitops_cluster_link	x		x		x

混沌工程

Resource Type	List	Get	Create	Update	Delete	Execute Actions
chaos_experiment	x	x	x		x	run, stop
chaos_experiment_run		x
chaos_experiment_variable	x
chaos_component_variable		x
chaos_input_set	x	x	x	x	x
chaos_experiment_template	x	x			x	create_from_template, list_revisions, get_variables, get_yaml, compare_revisions
chaos_probe	x	x	x		x	enable, verify, get_manifest
chaos_probe_in_run	x
chaos_probe_template	x	x			x	get_variables
chaos_infrastructure	x
chaos_k8s_infrastructure	x	x	x			check_health
chaos_enabled_infrastructure	x
chaos_environment	x
chaos_hub	x	x	x	x	x
chaos_hub_fault	x
chaos_fault	x	x			x	get_variables, get_yaml
chaos_fault_template	x	x			x	list_revisions, get_variables, get_yaml, compare_revisions
chaos_fault_experiment_run	x
chaos_action	x	x	x		x	get_manifest
chaos_action_template	x	x			x	list_revisions, get_variables, compare_revisions
chaos_loadtest	x	x	x	x	x	run, stop
chaos_service	x	x	x	x	x	list_experiment_runs, list_load_tests
custom_service	x	x	x	x
chaos_application_map	x	x
discovered_agent	x
discovered_namespace	x
discovered_service	x
discovered_network_map	x
chaos_guard_condition	x	x			x
chaos_guard_rule	x	x			x	enable
chaos_recommendation	x	x
chaos_risk	x	x
chaos_dr_test	x		x
scanned_risk	x	x				occurrences, summary_by_service
chaos_risk_rule	x	x	x	x	x
chaos_risk_scan	x	x	x	x	x	retry, abort, report, report_download, heatmap, submit_findings

Cloud Cost Management (CCM)

Resource Type	List	Get	Create	Update	Delete	Execute Actions
cost_perspective	x	x	x	x	x
cost_breakdown	x
cost_timeseries	x
cost_summary	x	x
cost_recommendation	x	x				update_state, override_savings, create_jira_ticket, create_snow_ticket
cost_anomaly	x
cost_anomaly_summary		x
cost_category	x	x
cost_account_overview		x
cost_filter_value	x
cost_recommendation_stats		x
cost_recommendation_detail		x
cost_commitment		x
ai_budget	x	x	x	x	x
ai_budget_overview		x
ai_budget_consumption	x
ai_budget_override_request	x	x	x			approve, reject

软件工程洞察（SEI）

SEI 资源经过整合，以提高令牌效率。使用 metric 或 aspect 参数获取 DORA、团队／组织树详情和 AI 洞察。

资源类型	列出	获取	创建	更新	删除	执行动作
sei_metric	x
sei_productivity_metric		x
sei_dora_metric		x				传入 metric：deployment_frequency、change_failure_rate、mttr、lead_time 或 *_drilldown
sei_team	x	x
sei_team_detail	x					传入 aspect：integrations、developers、integration_filters
sei_org_tree	x	x
sei_org_tree_detail	x	x				传入 aspect：efficiency_profile、productivity_profile、business_alignment_profile、integrations、teams
sei_business_alignment	x	x				传入 aspect：feature_metrics、feature_summary；使用 get 时传入 drilldown
sei_ai_usage	x	x				传入 aspect：metrics、breakdown、summary、top_languages
sei_ai_adoption	x	x				传入 aspect：metrics、breakdown、summary
sei_ai_impact		x				传入 aspect：pr_velocity、rework
sei_ai_raw_metric	x

软件供应链保障（SCS）

资源类型	列出	获取	创建	更新	删除	执行动作
scs_artifact_source	x
artifact_security	x	x
scs_artifact_component	x
scs_artifact_remediation		x
scs_chain_of_custody		x
scs_compliance_result	x
code_repo_security	x	x
scs_sbom		x

Evidence Vault

Evidence Vault 存储 in-toto 证明（SDLC 证据）。列表支持通过 resource_scope 指定账户／组织／项目范围。单个自由文本筛选条件（流水线、单独的制品、gitoid）使用 search_term；额外的名称条件使用 filters.subject_name；主题内容摘要使用 filters.subject_digest。Get 根据 gitoid_sha256 查找，并要求提供 org_id／project_id（取自列表行）。下载（harness_execute 操作 download）会返回有时限的 download_url——务必向用户展示该链接。需要启用功能标志 SCS_EVIDENCE_VAULT。

资源类型	列表	获取	创建	更新	删除	执行操作
attestation	x	x				download

安全测试编排（STO）

资源类型	列表	获取	创建	更新	删除	执行操作
security_issue	x
security_issue_filter	x
security_exemption	x		x			approve、reject
remediation_diff	x

security_exemption 创建属于 high_write 操作。服务会从经过身份验证的 PAT 中推导 requester_id，设置 exemptFutureOccurrences=true，并在未提供 duration_days 时将其默认设为 30。列出豁免项时，请传入较小的显式页面大小（例如 filters: { "status": "Pending", "size": 5 }），并使用每次响应中返回的 _nextPageHint 继续翻页。

安全豁免执行工作流：

• 使用 harness_list，并设置 resource_type="security_exemption"，以及明确的 status，例如 Pending、Approved、Rejected、Expired 或 Canceled。
• 使用 harness_execute，设置 action="approve"，并提供必需的 body.scope：CURRENT、ACCOUNT、ORG 或 PROJECT。CURRENT 会按豁免项现有的范围进行批准；其他范围会在内部使用 STO promote 端点。若未提供 body.approver_id，服务会自动填入经过身份验证的用户；body.comment 为可选项。
• 使用 action="reject" 拒绝豁免项。若未提供 body.approver_id，也会自动填入。
• 没有单独的 promote 执行操作。若要在账户、组织或项目范围内批准，请将 action="approve" 与非 CURRENT 的 body.scope 配合使用。

访问控制

资源类型	列表	获取	创建	更新	删除	执行操作
user	x	x
user_group	x	x	x	x	x
service_account	x	x	x		x
role	x	x	x		x
role_assignment	x		x
resource_group	x	x	x		x
permission	x

治理

资源类型	列表	获取	创建	更新	删除	执行操作
policy	x	x	x	x	x
policy_set	x	x	x	x	x
policy_evaluation	x	x

Deployment Freeze

Resource Type	List	Get	Create	Update	Delete	Execute Actions
freeze_window	x	x	x	x	x	toggle_status
global_freeze		x				manage

Service Overrides

Resource Type	List	Get	Create	Update	Delete	Execute Actions
service_override	x	x	x	x	x

Settings

Resource Type	List	Get	Create	Update	Delete	Execute Actions
setting	x

MCP Prompts

DevOps

提示词	描述	参数
build-deploy-app	端到端 CI/CD 工作流：扫描 git 仓库，生成 CI 流水线（构建并推送 Docker 镜像），发现或生成 K8s 清单，创建 CD 流水线并部署；CI 失败时自动重试（最多 5 次），CD 失败时自动重试（最多 3 次，需用户许可）。重试次数耗尽后，提供指向所有已创建资源的 Harness UI 深层链接，方便手动排查。	repoUrl（必填）、imageName（必填）、projectId（可选）、namespace（可选）
debug-pipeline-failure	分析失败的执行：接受执行 ID、流水线 ID 或 Harness URL。通过 harness_diagnose 获取阶段／步骤明细、失败详情、delegate 信息和失败步骤日志，然后提供根因分析和修复建议。自动跟进链式流水线故障。	executionId（可选）、projectId（可选）
pipeline_summarizer	获取并汇总流水线执行中的所有步骤日志。使用 harness_diagnose 并设置 include_logs: true, include_all_step_logs: true 获取每个步骤的日志，然后以表格展示步骤名称、状态、时长和发生情况（基于日志的摘要）。不会跳过任何步骤。	executionId（可选）、projectId（可选）
create-pipeline	根据自然语言需求生成新的流水线 YAML，并审查现有资源以获取上下文	description（必填）、projectId（可选）
create-agent	以交互方式构建 Harness AI Agent——检查现有 Agent（更新时检测当前的 agent.uses 格式或旧版 agent.step.group.steps 规范格式），收集需求，以适当格式生成 Agent 规范，与用户确认，然后通过 harness_create／harness_update 创建或更新	agent_name（必填）、task_description（必填）、org_id（可选）、project_id（可选）
onboard-service	引导新服务完成接入，包括环境和部署流水线	serviceName（必填）、projectId（可选）
dora-metrics-review	审查 DORA 指标（部署频率、变更失败率、MTTR、前置时间），并按 Elite／High／Medium／Low 分类，提供改进建议	teamRefId（可选）、dateStart（可选）、dateEnd（可选）
setup-gitops-application	引导完成 GitOps 应用接入——验证 Agent、集群和仓库，并创建应用	agentId（必填）、projectId（可选）
chaos-resilience-test	设计混沌实验，通过故障注入、探针和预期结果测试服务韧性	serviceName（必填）、projectId（可选）
feature-flag-rollout	规划并执行跨环境的渐进式功能标志发布，并设置安全门禁	flagIdentifier（必填）、projectId（可选）
migrate-pipeline-to-template	分析现有流水线，并从中提取可复用的阶段／步骤模板	pipelineId（必填）、projectId（可选）
delegate-health-check	检查 delegate 的连接状态、健康状况和令牌状态，并排查基础设施问题	projectId（可选）
developer-portal-scorecard	审查服务的 IDP 评分卡，并找出可改进开发者体验的不足之处	projectId（可选）
pending-approvals	查找等待审批的流水线执行，显示详情，并提供批准或拒绝选项	projectId（可选）、orgId（可选）、pipelineId（可选）

FinOps

提示词	描述	参数
optimize-costs	分析云成本数据，提供优化建议并发现异常，按潜在节省金额排序	projectId（可选）
cloud-cost-breakdown	按服务、环境或集群深入分析云成本，并进行趋势分析和异常检测	perspectiveId（可选）、projectId（可选）
commitment-utilization-review	分析预留实例和节省计划的利用率，找出浪费并优化承诺	projectId（可选）
cost-anomaly-investigation	调查成本异常 — 确定根本原因、受影响的资源和补救措施	projectId（可选）
rightsizing-recommendations	审查并排列资源规格调整建议的优先级，还可创建 Jira 或 ServiceNow 工单	projectId（可选）、minSavings（可选）

DevSecOps

提示词	描述	参数
security-review	审查 Harness 资源中的安全问题，并按严重程度提出补救建议	projectId（可选）、severity（可选，默认值：critical,high）
vulnerability-triage	对流水线和制品中的安全漏洞进行分类，按严重程度和可利用性排列优先级	projectId（可选）、severity（可选）
sbom-compliance-check	审计制品的 SBOM 和合规状况 — 许可证风险、策略违规和组件漏洞	artifactId（可选）、projectId（可选）
supply-chain-audit	端到端软件供应链安全审计 — 来源证明、监管链和策略合规	projectId（可选）
security-exemption-review	审查待处理的安全豁免，并批量决定批准或拒绝	projectId（可选）
bulk-exemption-create	为多个 STO 问题创建有充分理由的安全豁免，并明确范围和期限指导	projectId（必填）、exemption_type（必填）、reason（必填）、问题筛选条件（可选）
access-control-audit	审计用户权限、权限过高的账户和角色分配，以落实最小权限原则	projectId（可选）、orgId（可选）

Harness 代码

提示词	描述	参数
code-review	审查拉取请求 — 分析差异、提交、检查和评论，针对错误、安全性、性能和风格提供结构化反馈	repoId（必需）、prNumber（必需）、projectId（可选）
pr-summary	根据分支的提交历史和差异自动生成 PR 标题和描述	repoId（必需）、sourceBranch（必需）、targetBranch（可选，默认值：main）、projectId（可选）
branch-cleanup	分析仓库中的分支，并建议删除过时或已合并的分支	repoId（必需）、projectId（可选）

MCP 资源

资源 URI	描述	MIME 类型
pipeline:///{pipelineId}	Pipeline YAML 定义	application/x-yaml
pipeline:///{orgId}/{projectId}/{pipelineId}	Pipeline YAML（带有明确的作用域）	application/x-yaml
executions:///recent	最近 10 次 Pipeline 执行摘要	application/json
schema:///pipeline	Harness Pipeline JSON Schema	application/schema+json
schema:///template	Harness 模板 JSON Schema	application/schema+json
schema:///trigger	Harness 触发器 JSON Schema	application/schema+json
schema:///pipeline_v1 （Alpha）	Harness V1 Pipeline JSON Schema（简化的阶段/步骤格式）	application/schema+json
schema:///agent-pipeline	Harness AI Agent Pipeline JSON Schema	application/schema+json
agent-docs:///legacy-format	旧版 Agent 规范格式参考（agent.step.group.steps / PLUGIN_TASK），更新现有旧版格式 Agent 时由 create-agent 提示词读取	text/markdown

工具集筛选

默认情况下，46 个工具集中有 42 个已启用。四个工具集为选择启用，默认不包含：

• ansible — Harness Ansible（清单、playbook、主机、活动）。选择启用，因为它限定于项目范围，并会引入许多用户不需要的概念。
• autonomous_work — Development Harness（自主工作）。选择启用；范围请参阅工具集描述。
• observability-evaluations — 计划执行的生产遥测评估规则。选择启用，因为它依赖已部署的评分控制平面。
• registries-v3 — Harness Artifact Registry v3（软件包、版本、文件、元数据、扫描、防火墙例外）。在 v3 写入功能上线之前选择启用，以免 Agent 需要区分 v1 registries/artifacts 和 v3 packages/versions。

使用 + 前缀添加工具集

使用 + 前缀，可在所有默认工具集之外，明确添加选择启用的工具集：

# Explicitly include Ansible alongside all defaults
HARNESS_TOOLSETS=+ansible

移除默认工具集

使用 - 前缀，排除不需要的工具集：

# Remove chaos and ccm from defaults
HARNESS_TOOLSETS=-chaos,-ccm

组合使用 + 和 -

# Add Ansible, remove chaos
HARNESS_TOOLSETS=+ansible,-chaos

明确指定允许列表

使用不带前缀的逗号分隔列表，可完全替换默认工具集。仅启用列出的工具集：

# Only expose pipelines, services, and connectors
HARNESS_TOOLSETS=pipelines,services,connectors

可用的工具集名称：

工具集	资源类型
platform	organization, project
pipelines	pipeline, pipeline_v1, pipeline_dynamic_execution, execution, execution_inputs, trigger, pipeline_summary, input_set, approval_instance
agents	agent, agent_run
services	service
environments	environment
connectors	connector, connector_catalogue, llm_model
infrastructure	infrastructure
secrets	secret
logs	execution_log
audit	audit_event
delegates	delegate, delegate_token
repositories	repository, branch, commit, file_content, tag, repo_rule, space_rule
registries	registry, artifact, artifact_version, artifact_file
file_store	file_store
templates	template
dashboards	dashboard, dashboard_data
idp	idp_entity, scorecard, scorecard_check, scorecard_stats, scorecard_check_stats, idp_score, idp_workflow, idp_tech_doc
pull-requests	pull_request, pr_reviewer, pr_comment, pr_check, pr_activity
feature-flags	fme_workspace, fme_environment, fme_feature_flag, fme_feature_flag_definition, fme_rollout_status, fme_rule_based_segment, fme_rule_based_segment_definition, fme_traffic_type, fme_identity, fme_standard_segment, fme_segment_keys, fme_segment, fme_segment_definition, fme_metric, fme_event_type, fme_experiment, fme_experiment_settings, fme_experiment_alerting, fme_experiment_result
gitops	gitops_agent, gitops_agent_metrics, gitops_argo_project, gitops_app_project_mapping, gitops_autocreate_log, gitops_application, gitops_cluster, gitops_repository, gitops_applicationset, gitops_repo_credential, gitops_app_event, gitops_pod_log, gitops_managed_resource, gitops_resource_action, gitops_dashboard, gitops_app_resource_tree, gitops_cluster_link
chaos	chaos_experiment, chaos_experiment_run, chaos_experiment_variable, chaos_component_variable, chaos_input_set, chaos_experiment_template, chaos_probe, chaos_probe_in_run, chaos_probe_template, chaos_infrastructure, chaos_k8s_infrastructure, chaos_enabled_infrastructure, chaos_environment, chaos_hub, chaos_hub_fault, chaos_fault, chaos_fault_template, chaos_fault_experiment_run, chaos_action, chaos_action_template, chaos_loadtest, chaos_service, custom_service, chaos_application_map, discovered_agent, discovered_namespace, discovered_service, discovered_network_map, chaos_guard_condition, chaos_guard_rule, chaos_recommendation, chaos_risk, chaos_dr_test, scanned_risk, chaos_risk_rule, chaos_risk_scan
ccm	cost_perspective, cost_breakdown, cost_timeseries, cost_summary, cost_recommendation, cost_anomaly, cost_anomaly_summary, cost_category, cost_account_overview, cost_filter_value, cost_recommendation_stats, cost_recommendation_detail, cost_commitment
sei	sei_metric, sei_productivity_metric, sei_dora_metric, sei_team, sei_team_detail, sei_org_tree, sei_org_tree_detail, sei_business_alignment, sei_ai_usage, sei_ai_adoption, sei_ai_impact, sei_ai_raw_metric
scs	scs_artifact_source, artifact_security, scs_artifact_component, scs_artifact_remediation, scs_chain_of_custody, scs_compliance_result, code_repo_security, scs_sbom
evidence-vault	attestation
sto	security_issue, security_issue_filter, security_exemption, remediation_diff
dbops	database_schema, database_instance, database_snapshot_object, database_llm_authoring_pipeline
autonomous_work （选择启用）	work_item, work_item_resume, work_item_approve, work_timeline, work_budget, work_phase, work_phase_artifact, work_artifact, budget, budget_grant, budget_usage, work_class, work_trigger, capability, risk_evaluator, team, member, member_template, software_component, content_source_connector
access_control	user, user_group, service_account, role, role_assignment, resource_group, permission
governance	policy, policy_set, policy_evaluation
freeze	freeze_window, global_freeze
overrides	service_override
settings	setting
knowledge-graph	kg_queryable_type_summary, kg_grammar, hql_query
semantic-layer	kg_type, kg_related_type
ai-evals	eval_dataset, eval_dataset_item, evaluation, eval_run, eval_run_item, eval_run_by_eval, eval_metric, eval_metric_set, eval_metric_set_entry, eval_suite, eval_suite_evaluation, eval_suite_run, eval_target, eval_annotation, eval_analytics, eval_git_settings, eval_git_registration, eval_prompt, online_eval
observability-evaluations （选择启用）	observability_eval
iacm	iacm_workspace, iacm_variable_set, iacm_resource, iacm_module, iacm_provider, iacm_workspace_costs, iacm_activity_resource_change
ansible （选择启用）	ansible_inventory, ansible_playbook, ansible_host, ansible_host_activity, ansible_activity
registries-v3 （选择启用）	package_v3, version_v3, file_v3, registry_metadata_v3, package_metadata_v3, version_metadata_v3, file_metadata_v3, metadata_key_v3, metadata_value_v3, artifact_scan_v3, bulk_scan_evaluation_v3, firewall_exception_v3, firewall_exception_version_v3
release-management	release_process, release_activity, release, release_execution_phase, release_execution_task, release_execution_activity, release_input, release_execution_phase_input, release_execution_phase_output, release_execution_activity_input, release_execution_activity_output
vibe	vibe_project, vibe_app_lifecycle
timelines	activity_timeline

架构

                 +------------------+
                 |   AI Agent       |
                 |  (Claude, etc.)  |
                 +--------+---------+
                          |  MCP (stdio or HTTP)
                 +--------v---------+
                |    MCP Server     |
                | 11 Generic Tools  |
                 +--------+---------+
                          |
                 +--------v---------+
                |    Registry       |  <-- Declarative resource definitions
                | 46 Toolsets (42 default) |
                |  263 Resource Types|
                 +--------+---------+
                          |
                 +--------v---------+
                 |  HarnessClient    |  <-- Auth, retry, rate limiting
                 +--------+---------+
                          |  HTTPS
                 +--------v---------+
                 |  Harness REST API |
                 +-------------------+

工作原理

1. 工具是通用动词：harness_list、harness_get 等。它们接受一个 resource_type 参数，该参数会路由到正确的 API 端点。
2. 注册表将每个 resource_type 映射到一个 ResourceDefinition——一种声明式数据结构，用于指定 HTTP 方法、URL 路径、路径/查询参数映射以及响应提取逻辑。
3. 分发会解析资源定义、构建 HTTP 请求（路径替换、查询参数、按 resource_scope 注入账户/组织/项目），通过 HarnessClient 调用 Harness API，并提取相关响应数据。
4. 工具集筛选（HARNESS_TOOLSETS）控制启动时加载到注册表中的资源定义。
5. 结构化输出通过 MCP outputSchema 声明；harness_list 会将数组和常见列表包装对象转换为对象形式的 structuredContent，以适配严格客户端。
6. 深层链接会自动附加到响应中，为每个资源提供直接跳转到 Harness UI 的 URL。
7. 精简模式会从列表结果中移除冗长的元数据，只保留可执行操作的字段（标识、状态、类型、时间戳、深层链接），以尽量减少令牌用量。

添加新资源类型

在 src/registry/toolsets/ 中创建新文件，或向现有工具集中添加资源：

// src/registry/toolsets/my-module.ts
import type { ToolsetDefinition } from "../types.js";

export const myModuleToolset: ToolsetDefinition = {
  name: "my-module",
  displayName: "My Module",
  description: "Description of the module",
  resources: [
    {
      resourceType: "my_resource",
      displayName: "My Resource",
      description: "What this resource represents",
      toolset: "my-module",
      scope: "project",                    // "project" | "org" | "account"
      identifierFields: ["resource_id"],
      listFilterFields: ["search_term"],
      operations: {
        list: {
          method: "GET",
          path: "/my-module/api/resources",
          queryParams: { search_term: "search", page: "page", size: "size" },
          responseExtractor: (raw) => raw,
          description: "List resources",
        },
        get: {
          method: "GET",
          path: "/my-module/api/resources/{resourceId}",
          pathParams: { resource_id: "resourceId" },
          responseExtractor: (raw) => raw,
          description: "Get resource details",
        },
      },
    },
  ],
};

然后在 src/registry/index.ts 中导入它，并将其添加到 ALL_TOOLSETS 数组中。无需更改任何工具文件。

开发

# Build
pnpm build

# Watch mode
pnpm dev

# Type check
pnpm typecheck

# Run tests
pnpm test

# Watch tests
pnpm test:watch

# Interactive MCP Inspector
pnpm inspect

# Refresh generated README counts from the built registry
pnpm docs:generate

# Verify README counts and clone instructions are current
pnpm docs:check

# Sync and verify JSON Schemas used by harness_schema
pnpm sync-schemas
pnpm check-schema-coverage

项目结构

src/
  index.ts                          # Entrypoint, transport setup
  config.ts                         # Env var validation (Zod)
  client/
    harness-client.ts               # HTTP client (auth, retry, rate limiting)
    types.ts                        # Shared API types
  registry/
    index.ts                        # Registry class + dispatch logic
    types.ts                        # ResourceDefinition, ToolsetDefinition, etc.
    toolsets/                        # One file per toolset (declarative data)
      platform.ts
      pipelines.ts
      services.ts
      ccm.ts
      access-control.ts
      ...
  tools/                            # 11 generic MCP tools
    harness-list.ts
    harness-get.ts
    harness-create.ts
    harness-update.ts
    harness-delete.ts
    harness-execute.ts
    harness-search.ts
    harness-diagnose.ts
    harness-describe.ts
    harness-status.ts
    harness-schema.ts

  resources/                        # MCP resource providers
    pipeline-yaml.ts
    execution-summary.ts
  prompts/                          # MCP prompt templates
    build-deploy-app.ts             # DevOps: end-to-end build & deploy workflow
    debug-pipeline.ts               # DevOps: debug failed executions
    create-pipeline.ts              # DevOps: generate pipeline from requirements
    onboard-service.ts              # DevOps: onboard new service
    dora-metrics.ts                 # DevOps: DORA metrics review
    setup-gitops.ts                 # DevOps: GitOps application setup
    chaos-resilience.ts             # DevOps: chaos experiment design
    feature-flag-rollout.ts         # DevOps: progressive flag rollout
    migrate-to-template.ts          # DevOps: extract templates from pipeline
    delegate-health.ts              # DevOps: delegate health check
    developer-scorecard.ts          # DevOps: IDP scorecard review
    optimize-costs.ts               # FinOps: cost optimization
    cloud-cost-breakdown.ts         # FinOps: cost deep-dive
    commitment-utilization.ts       # FinOps: RI/savings plan analysis
    cost-anomaly.ts                 # FinOps: anomaly investigation
    rightsizing.ts                  # FinOps: rightsizing recommendations
    security-review.ts              # DevSecOps: security issue review
    vulnerability-triage.ts         # DevSecOps: vulnerability triage
    sbom-compliance.ts              # DevSecOps: SBOM compliance audit
    supply-chain-audit.ts           # DevSecOps: supply chain audit
    exemption-review.ts             # DevSecOps: exemption approval
    access-control-audit.ts         # DevSecOps: access control audit
    code-review.ts                  # Harness Code: PR code review
    pr-summary.ts                   # Harness Code: auto-generate PR summary
    branch-cleanup.ts               # Harness Code: stale branch cleanup
    pending-approvals.ts            # Approvals: find and act on pending approvals
  utils/
    cli.ts                          # CLI arg parsing (transport, port)
    errors.ts                       # Error normalization
    logger.ts                       # stderr-only logger
    progress.ts                     # MCP progress & logging notifications
    rate-limiter.ts                 # Client-side rate limiting
    deep-links.ts                   # Harness UI deep link builder
    response-formatter.ts           # Consistent MCP response formatting
    compact.ts                      # Compact list output for token efficiency
tests/
  config.test.ts                    # Config schema validation tests
  utils/
    response-formatter.test.ts
    deep-links.test.ts
    errors.test.ts
  registry/
    registry.test.ts                # Registry loading, filtering, dispatch tests

征求确认

写入工具（harness_create、harness_update、harness_delete、harness_execute）使用 MCP 征求确认，仅当操作风险等级为 medium_write、high_write 或 destructive 时，才会提示用户确认。低风险的创建 / 更新 / 读取操作（例如 pipeline.create、pipeline.update、hql_query.run）会静默执行，不会提示。出现提示时，用户可以查看即将执行的操作并选择接受或拒绝，从而对实际修改或运行内容的操作进行真正的人工审核。

工作原理：

1. LLM 调用风险等级为 medium_write 或更高的写入工具（例如 harness_delete、harness_execute pipeline.run）。低风险的创建 / 更新 / 读取操作不会显示提示。
2. 服务端向客户端发送征求确认请求，其中包含操作摘要和一个 confirm 复选框（默认勾选）。
3. 用户查看详情后，点击 接受（勾选 confirm）或 拒绝 / 取消。
4. 如果用户勾选 confirm: true 并接受，操作就会继续执行。如果用户接受时未勾选 confirm、拒绝或取消，操作就会被阻止，并告知 LLM（明确拒绝具有决定性，不会被工具调用中的 confirm: true 绕过）。

客户端支持情况：

客户端	是否支持征求确认
Cursor	是
VS Code (Copilot)	是
Claude Desktop	尚不支持
Devin Desktop	尚不支持
MCP Inspector	是

客户端不支持征求确认时，具体行为会因操作风险而异：

风险等级	客户端支持征求确认	传入 confirm: true	行为
read、low_write	任意	任意	静默执行——不会显示提示（此风险等级下 confirm 不起作用）
medium_write、high_write、destructive	是	任意	提示用户。仅当用户接受并且 confirm: true（架构中的默认值）时才继续执行。明确拒绝、取消，或接受时传入 confirm: false（用户取消勾选）均具有决定性，不会被工具调用中的 confirm: true 绕过。接受时缺少 confirm 字段，则视为客户端未能显示可用的提示；可通过重试并传入 confirm: true 来恢复
medium_write、high_write、destructive	否	否	阻止（返回错误并提示使用 confirm: true 重试）
medium_write、high_write、destructive	否	是	继续执行（非交互式自动化的显式选择加入）
任意（不高于 HARNESS_AUTO_APPROVE_RISK）	任意	任意	自动批准，不提示

如果 elicitInput 在运行时因传输错误或不支持该方法而失败，对于风险等级为 medium_write 或更高的操作，除非调用方传入 confirm: true，否则调用会被阻止。如果客户端无法显示提示，或返回了缺少 confirm 字段的退化接受结果（{action: "accept"}），则会将 confirm: true 作为后备选项予以接受；但如果客户端已完成征求确认握手并明确拒绝或取消，confirm: true 不会覆盖该决定。

自主模式

自主模式意味着服务会执行所有操作，包括写入和破坏性操作，而不会提示确认。设置以下内容即可启用：

HARNESS_AUTO_APPROVE_RISK=all

这是部署级别的上限：设置后，单个会话无法超出此上限（不过，可以通过 x-harness-auto-approve-risk 标头为每个会话选择更严格的阈值）。

或者在 MCP 客户端配置中设置：

{
  "mcpServers": {
    "harness": {
      "command": "npx",
      "args": ["harness-mcp-v2"],
      "env": {
        "HARNESS_API_KEY": "pat.xxx.xxx.xxx",
        "HARNESS_AUTO_APPROVE_RISK": "all"
      }
    }
  }
}

**部分自主：**你也可以只自动批准特定风险级别以下的操作，同时仍对更高风险的操作提示确认：

# Auto-approve reads and low-risk writes; prompt for medium_write, high_write, destructive
HARNESS_AUTO_APPROVE_RISK=low_write

# Auto-approve up to high-risk writes; only prompt for destructive operations
HARNESS_AUTO_APPROVE_RISK=high_write

值	自动批准的内容
none（默认）	无——不设置自动批准阈值
low_write	读取操作 + 低风险写入操作
medium_write	读取操作 + 低风险和中风险写入操作
high_write	读取操作 + 低风险、中风险和高风险写入操作
all	所有操作，包括破坏性操作

自主模式警告：HARNESS_AUTO_APPROVE_RISK=all 会跳过所有操作的确认，包括 harness_delete。请谨慎使用，并考虑配合 HARNESS_TOOLSETS 限制可用的资源类型。

**迁移说明：**仍支持 HARNESS_SKIP_ELICITATION=true，并会将其映射到 HARNESS_AUTO_APPROVE_RISK=all。stderr 中会记录弃用警告。如果两者都已设置，则以 HARNESS_AUTO_APPROVE_RISK 为准。

安全性

• 绝不暴露机密。secret 资源类型仅返回元数据（名称、类型、作用域），任何响应中都不会包含机密值。
• **需要确认的操作在可用时会使用征询。**当写入或执行操作的风险为 medium_write、high_write 或 destructive 时，harness_create、harness_update、harness_delete 和 harness_execute 会在继续操作前尝试使用 MCP 征询（请参阅征询）。低风险操作（read、low_write，例如 pipeline.create、pipeline.update、hql_query.run）会静默执行，不会提示。
• **中风险及以上操作在无法确认时会安全失败。**如果无法为 medium_write、high_write 或 destructive 操作获取确认，这些操作会被阻止，而不会在未确认的情况下执行。自主工作流可通过 HARNESS_AUTO_APPROVE_RISK 覆盖此行为。
• **CORS 限制为同源。**HTTP 传输仅允许同源请求，以防恶意网站针对 localhost 上的 MCP 服务发起 CSRF 攻击。
• **HTTP 速率限制。**HTTP 传输会将每个 IP 每分钟的请求数限制为 60，以防止请求泛滥。
• **API 速率限制。**Harness API 客户端会将请求速率限制为每秒 10 次，以避免触及上游速率限制。
• **强制分页边界。**列表查询总数上限为 10,000 项，每页上限为 100 项，以防止内存耗尽。
• **失败重试并采用退避策略。**对于暂时性故障（HTTP 429、5xx），会采用指数退避和随机抖动进行重试。
• **绑定到 localhost。**HTTP 传输默认绑定到 127.0.0.1，无法从网络访问。
• **不向 stdout 写入日志。**所有日志都会写入 stderr，以免破坏 stdio JSON-RPC 传输。

配套技能

Harness MCP 服务与 Harness Skills 配合使用效果很好。它是一组现成的 Claude Code 技能（斜杠命令），专为常见的 Harness 工作流设计。将它们与此 MCP 服务一同安装，即可使用 /deploy、/rollback、/triage 等高级自动化功能，无需编写自定义提示词。

故障排除与常见问题

症状	可能原因	处理方法
HARNESS_ACCOUNT_ID is required when the API key does not include an account ID segment...	API 密钥不符合受支持的账户范围格式（pat.<accountId>... 或 sat.<accountId>...），因此无法推断账户 ID	显式设置 HARNESS_ACCOUNT_ID
启动时出现 Unknown transport: "..."	不支持的 CLI 传输参数	仅使用 stdio 或 http
启动时出现 Invalid HARNESS_TOOLSETS: ...	一个或多个工具集名称无法识别	仅使用工具集筛选中的名称（必须完全匹配）
HTTP 出现 mcp-session-id header is required...	发送会话请求时未提供会话标头	先发送 initialize，然后在 POST/GET/DELETE /mcp 请求中包含 mcp-session-id
HTTP 出现 Session not found...	会话空闲达到 MCP_SESSION_TTL_MS 毫秒后过期，或已关闭	重新运行 initialize 创建新会话，然后使用新标头重试
HTTP 在 /mcp 上出现 405 Method Not Allowed	MCP 端点不支持此方法	仅使用 POST、GET、DELETE 或 OPTIONS
HTTP 出现 Invalid request	JSON 请求体无效，或请求体超出 HARNESS_MAX_BODY_SIZE_MB	验证 JSON 负载的大小和结构；如有需要，增大 HARNESS_MAX_BODY_SIZE_MB
工具返回 Unknown resource_type "..."	资源类型拼写错误，或已通过 HARNESS_TOOLSETS 筛除	调用 harness_describe（可选传入 search_term）以查找有效类型
出现 Missing required field "... for path parameter ..."	项目或组织范围的调用缺少标识符	设置 HARNESS_ORG/HARNESS_PROJECT，或在每次工具调用中传入 org_id/project_id
出现 resource_scope "org" requires org_id... 或 resource_scope "project" requires project_id...	多范围资源被强制指定为组织或项目范围，但标识符不足	传入缺少的 org_id/project_id，配置 HARNESS_ORG/HARNESS_PROJECT，或在支持时使用 resource_scope: "account"
出现 Read-only mode is enabled ... operations are not allowed	HARNESS_READ_ONLY=true 会阻止创建、更新、删除和执行操作	如需执行写入操作，请设置 HARNESS_READ_ONLY=false
流水线运行在预检阶段因必需输入未解析而失败	提供的 inputs 未覆盖必需的运行时占位符	获取 runtime_input_template，提供缺少的简单键，或对结构化输入使用 input_set_ids
流水线 CI 简写（branch、tag、pr_number、commit_sha）未生效	已提供 inputs.build，因此按预期跳过了简写展开	移除 inputs.build 以使用简写展开，或保留完整的显式 build 结构
流水线运行加载了错误的 YAML 修订版本	流水线定义存储在 Git 中，但运行时未指定所需的流水线分支	在 run 操作中传入 params.pipeline_branch；它会映射到 Harness 的 branch
wait: true 返回了 _wait.error	流水线触发成功，但服务端轮询失败	使用 harness_get(resource_type="execution", ...) 重新检查 execution_id，再决定是否重新运行
wait: true 返回了 execution_timed_out: true	执行在 wait_timeout_seconds 之前未达到终止状态	使用返回的 execution_id 重新检查状态；等待其达到终止状态后再运行 harness_diagnose
执行日志为空，或 Blob 下载返回 403	Harness 托管的日志 Blob URL 需要通过配置好的 Harness 客户端和身份验证路径访问，尤其是在内部或自托管主机上	将 HARNESS_BASE_URL 保持为指向目标 Harness 主机，并使用 harness_get(resource_type="execution_log", ...) 或 harness_diagnose(..., include_logs=true)，而不是绕过 MCP 客户端
Operation declined by user / Operation cancelled by user	用户拒绝或取消了 elicitation 确认对话框——此结果具有权威性	与用户确认操作详情；confirm: true 不会绕过明确的拒绝。用户必须接受提示
Operation blocked: the client could not surface a usable confirmation prompt	客户端不支持 elicitation、elicitInput 失败，或返回了无效的接受结果	对非交互式自动化，请使用 confirm: true 重试；或者使用支持 elicitation 的客户端
模板创建/更新时出现 body.template_yaml (or body.yaml) is required	模板 API 需要完整的 YAML 负载	在 body 中提供完整的 template_yaml 字符串；删除时，传入 version_label 以删除单个版本（省略则删除所有版本）
启动时出现 HARNESS_BASE_URL must use HTTPS	HARNESS_BASE_URL 设置为 HTTP URL	使用 HTTPS；或在本地开发时设置 HARNESS_ALLOW_HTTP=true

License

MIT