Harness

官方

访问并与Harness平台数据进行交互，包括管道、仓库、日志和制品仓库。

GitHub

104

试用此 MCP赞助

你可以用 Harness MCP 做什么？

列出 Harness 资源 — 让您的 AI 使用 harness_list 列出组织、项目、流水线或其他资源。
检索资源详情 — 通过 harness_get 获取任何 Harness 资源（如流水线或服务）的完整详细信息。
创建新资源 — 指示您的 AI 使用 harness_create 创建流水线、服务或其他实体。
跨项目发现 — 查询所有项目中失败的执行或资源；代理会动态导航账户层级结构。
多用户认证 — 在共享部署中，每个会话可通过 x-harness-api-key 请求头使用自己的 Harness API 密钥进行认证。

文档

Harness MCP Server 2.0

一个 MCP（模型上下文协议）服务器，通过 11 个整合工具和 255 种资源类型，让 AI 代理获得对 Harness.io 平台的完整访问权限。

为什么使用这个 MCP 服务器

大多数 MCP 服务器将每个 API 端点映射为一个工具。对于像 Harness 这样广泛的平台，这意味着 240+ 个工具——而随着工具数量的增长，LLM 在工具选择上的表现会变差。上下文窗口被模式（schema）填满，每个新端点都意味着新代码。

这个服务器的构建方式不同：

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

前提条件

在安装或运行服务器之前，您需要一个 Harness API 密钥：

登录您的 Harness 账户
前往 我的个人资料 → API 密钥 → + 新建 API 密钥
在 API 密钥下创建一个新的令牌——这将生成格式为 <prefix>.<accountId>.<tokenId>.<secret> 的 PAT 或 SAT
将令牌保存在安全的地方——下一步会用到

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

快速开始

选项 0：托管的 Harness MCP

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

重要提示： 托管 MCP 服务使用 Harness 平台 OAuth，而非 HARNESS_API_KEY。此外，该服务必须由 Harness 支持团队 按账户启用/配置后才能使用该端点。

配置示例请参阅托管的 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>...）中自动提取，因此 HARNESS_ACCOUNT_ID 仅对没有嵌入账户段的 API 密钥是必需的。

选项 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-shrinkwrap.json 使用 npm 的扁平布局安装。固定版本的官方 MCPB CLI 对其进行验证并创建 dist/harness-mcp-server-<version>.mcpb。

匹配 v*.*.* 的版本标签会自动将该捆绑包发布到对应的 GitHub 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`	启用 `HARNESS_MCP_MODE=oauth` 时的 RFC 9728 元数据
`/.well-known/oauth-protected-resource/mcp`	`GET`	默认 `/mcp` 资源的路径感知 RFC 9728 元数据

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 并完成 OAuth 2.1 授权码 + PKCE。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 基础地址 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 作用域填充。每个会话存储调用者的访问令牌，并将其作为 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。

多用户模式

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

服务器配置中不得设置 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 重绑定保护的主机头验证，CORS 限制浏览器来源。两者都不是认证；请使用 HARNESS_MCP_AUTH_TOKEN 或经过认证的网关/反向代理进行访问控制。

客户端配置

注意： HARNESS_ORG 和 HARNESS_PROJECT 是可选的。它们设置未在每次工具调用中指定时使用的组织 ID 和项目 ID。代理可以使用 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 平台 OAuth。它不使用客户端配置中的 HARNESS_API_KEY。托管 MCP 的可用性是按 Harness 账户配置的，因此您需要与 Harness 支持合作，才能在使用前启用/配置该设置。

托管端点 https://mcp.harness.io/mcp 是一项托管服务。Claude、Cursor 或 Cowork 中的客户端 MCP 配置无法覆盖其路由到的 Harness 环境。对于 Harness0 或其他私有 Harness SaaS 环境，请让 Harness 支持为该环境启用/配置托管 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；将 which node 中的目录放在 PATH 的前面。

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；将 which node 中的目录放在 PATH 的前面。

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 协议，并支持 stdio 和 HTTP 传输，因此它可以在任何符合 MCP 规范的网关后面运行，无需修改代码。

为什么使用网关？

集中式凭据管理——代理配置中无需 API 密钥
跨团队所有工具调用的治理与审计日志
为代理提供单一端点，而非 N 个到 N 个 MCP 服务器的连接
访问控制——限制哪些团队可以使用哪些工具

Docker MCP 网关

在您的 Docker MCP 网关配置中注册服务器：

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

Portkey

将 Harness MCP 服务器添加到您的 Portkey MCP 网关，以实现企业治理、成本跟踪和多 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 网关

服务器通过 HTTP 传输与 Envoy AI 网关的 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 代理插件通过您现有的 Kong 网关基础设施公开 Harness MCP 服务器。

其他网关

任何支持 MCP 规范的网关（Microsoft MCP 网关、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 个副本，带有就绪/存活探针、资源限制和非根安全上下文。Service 在内部暴露端口 80（目标为容器端口 3000）。

配置

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

变量	必填	默认值	描述
`HARNESS_MCP_MODE`	否	`single-user`	部署模式：`single-user`（共享 API 密钥）、`multi-user`（HTTP，每个会话使用独立 API 密钥）或 `oauth`（HTTP，使用 HarnessID 访问令牌验证）
`HARNESS_API_KEY`	是*	--	Harness 个人访问令牌或服务账户令牌。在 `single-user` 模式下必填。在 `multi-user` 或 `oauth` 模式下不得设置，因为每个会话自带凭据
`HARNESS_ACCOUNT_ID`	否	(来自 PAT/SAT)	Harness 账户标识符。在单用户模式下从 PAT/SAT 令牌自动提取；多用户会话可在 API 密钥未嵌入账户 ID 时通过 `x-harness-account-id` 自行提供
`HARNESS_BASE_URL`	否	`https://app.harness.io`（OAuth 模式下为 `https://mcp.harness.io/cli`）	Harness API/UI 基础 URL。OAuth 模式默认通过托管的 MCP `/cli` 代理路由；其他模式直接使用 Harness SaaS API
`HARNESS_MCP_OAUTH_ISSUER`	否	`https://id.harness.io/idp/realms/HarnessIDP`	HarnessID 签发方，与访问令牌的 `iss` 声明精确匹配
`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_FME_API_KEY`	否	--	可选的单用户/自托管 FME/Split 管理员凭据，仅用于旧版（`workspace_id`）模式下的 `fme_` 资源。旧版 FME 在 OAuth 模式下不可用，因此 HarnessID 令牌绝不会发送到 `api.split.io`；请改用 Harness 原生 `org_id`+`project_id` 作用域。在 `multi-user` 或 `oauth` 模式下不得设置
`HARNESS_FME_BASE_URL`	否	`https://api.split.io`	Split/FME 管理员 API 基础 URL，仅用于旧版（`workspace_id`）模式下的 `fme_` 资源。HTTP URL 需要 `HARNESS_ALLOW_HTTP=true` 用于本地开发。Harness 原生（`org_id`+`project_id`）模式忽略此项，改用标准 `HARNESS_API_KEY`/`HARNESS_BASE_URL`
`HARNESS_ORG`	否	--	组织 ID。当每次工具调用未指定 `org_id` 时使用。若省略，必须显式提供 `org_id`。代理还可通过 `harness_list(resource_type="organization")` 动态发现组织
`HARNESS_PROJECT`	否	--	项目 ID。当每次工具调用未指定 `project_id` 时使用。代理还可通过 `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_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）管道 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 令牌。非回环单用户和多用户绑定默认必填。在 `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 审计跨度
`HARNESS_SEARCH_PROVIDER`	否	`local`	语义搜索后端：`local`（进程内 ONNX 嵌入，默认）、`remote`（通过 HTTP 的外部搜索服务，多用户模式必需）或 `none`（禁用语义搜索，仅回退到关键字散列收集）。在气隙环境或启动时模型加载不可取的情况下使用 `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`	用于 `@huggingface/transformers` 搜索提供程序的 `local` 模型缓存目录。Docker 镜像将模型预烘焙到 `/app/.cache/hf` 以避免运行时下载。在生产部署中设置为持久卷路径
`HARNESS_DIAGNOSE_LOG_FETCH_CONCURRENCY`	否	`3`	`harness_diagnose` 在获取失败步骤日志时发起的最大并发日志块下载数。仅当诊断延迟主要由日志获取墙钟时间主导且 Pod 有内存余量时增加

语义搜索

harness_search 使用语义路由来缩小 scatter-gather API 调用的范围，然后再分发到 Harness。目前提供三种搜索提供程序：

提供程序	使用时机
`local`（默认）	单用户 stdio 模式。通过 `@huggingface/transformers` 在进程内运行 `all-MiniLM-L6-v2`。首次使用时下载约 23 MB 的模型；后续启动使用缓存。
`remote`	多用户 HTTP 模式（Harness 托管）。将嵌入和检索委托给外部搜索服务。通过 `tenant_id` 强制实施租户隔离——静态知识/文档使用 `global`，按账户划分的实体数据使用账户 ID。
`none`	完全禁用语义搜索；回退到跨所有资源类型的关键字 scatter-gather。

远程提供程序配置：

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。失败的批次会以有限容量重新入队，最终以警告方式丢弃，而不会阻塞工具执行。
OTEL_EXPORTER_OTLP_ENDPOINT 在安装了可选的 OpenTelemetry 对等依赖项时启用审计跨度。该接收器在已注册 tracer provider 时复用现有 provider，否则会引导独立的 OTLP 导出器。

每个事件包含工具名称、资源类型、操作、标识符、时间戳、风险、结果、HTTP 方法/路径、持续时间以及适用的确认方法。审计接收器是尽力而为的遥测；投递问题会被记录，绝不会重放或更改底层 Harness API 操作。有关 OTel 设置详情和跨度属性，请参阅 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，注册表将使用资源的默认范围和配置的默认值，除非标记为可选范围的资源在未显式传递时可能省略组织/项目。当路径包含账户级或项目级上下文时，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 定义和示例。流水线/模板 schema 已捆绑；连接器、环境、服务、密钥和基础设施 schema 是从捆绑快照或 NG `/yaml-schema` 获取的、具有作用域感知能力的实体 schema；`release_process` 和 `release_activity` schema 从 RMG `/api/yamlSchema` 实时获取。支持通过 `path` 进行深入钻取。
`harness_list`	列出指定类型的资源，支持过滤、搜索和分页。
`harness_get`	按标识符获取单个资源。
`harness_create`	创建新资源。支持内联和远程（基于 Git 的）流水线。通过 elicitation 提示用户确认。
`harness_update`	更新现有资源。支持内联和远程（基于 Git 的）流水线。通过 elicitation 提示用户确认。
`harness_delete`	删除资源。通过 elicitation 提示用户确认。具有破坏性。
`harness_execute`	对资源执行操作（运行/重试流水线、从 Git 导入流水线、切换开关、同步应用）。通过 elicitation 提示用户确认。对于流水线运行，请使用下面的运行时输入工作流（支持 `branch`/`tag`/`pr_number`/`commit_sha` 简写展开）。
`harness_search`	使用单个查询跨 Harness 资源类型进行搜索。使用语义路由（本地 `all-MiniLM-L6-v2` ONNX 嵌入，384 维）从启动时索引的 `knowledge` 语料库预测相关资源类型——通常在散射-聚合之前将约 163 种类型缩小到 1–8 种。当语义置信度较低时，回退到完整的关键字散射-聚合。当路由触发时，响应包含 `semantic_routed` 和 `types_skipped`。有关如何使新资源类型可被发现，请参阅 `docs/search-guidelines.md`。
`harness_diagnose`	诊断 `pipeline`、`connector`、`delegate` 和 `gitops_application` 资源（别名：`execution` -> `pipeline`、`gitops_app` -> `gitops_application`）。对于流水线，返回阶段/步骤耗时和失败详情；对于连接器/委托/GitOps 应用，返回针对性的健康和故障排查信号。
`harness_status`	获取实时项目健康仪表板——最近的执行、失败率和深层链接。

Schema 查找工作流

在创建或更新基于 YAML 的资源之前，使用 harness_schema，以便代理可以复制精确的字段名称和约束，而不是根据描述猜测。

捆绑的 schema 包括 pipeline、template、trigger、pipeline_v1、template_v1、inputSet_v1、overlayInputSet_v1 和 agent-pipeline。
实体 schema 包括 connector、environment、service、secret 和 infrastructure。它们具有作用域感知能力（account、org 或 project），当所选作用域需要时，需要 org_id/project_id。
发布管理定义（release_process、release_activity）从 RMG /api/yamlSchema 实时获取 JSON Schema（未捆绑）。当作用域限定到组织或项目时，传递 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" }

诊断委托健康状态：

{ "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"]
  }
}

流水线运行工作流（推荐）

对于 v0 流水线，使用以下顺序以减少执行时的输入错误：

发现必需的运行时输入

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

选择输入策略

简单变量： 传递扁平键值对 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 优先）。

执行运行

harness_execute(resource_type="pipeline", action="run", resource_id="<pipeline_id>", ...)
对于应从非默认分支加载 YAML 的基于 Git 的流水线，传递 params.pipeline_branch（作为 branch 发送到 Harness）。此显式定义选择器优先于 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
}
```

可选：组合两者

使用 input_set_ids 作为基础形状，使用 inputs 进行简单覆盖。

对于 v1 流水线：

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

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

动态流水线执行

当代理或外部系统在运行时生成完整的 v0 流水线 YAML，并需要针对现有的 Harness 流水线外壳运行它时，请使用 pipeline_dynamic_execution.run。这不能替代常规的 pipeline.run：保存的 v0 流水线必须已存在，账户级和流水线级的 允许动态执行 必须已启用，并且调用者需要对流水线具有编辑和执行权限。

{
  "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.yaml 可以是 YAML 字符串或 JSON 流水线对象；JSON 会在请求前序列化为 YAML。
此 API 不会解析运行时 <+input> 占位符。请提交完全解析的 YAML。
动态执行端点不支持输入集、选择性阶段执行、重试和触发器。
该操作是 high_write，并使用正常的确认/自动批准路径。响应会将 API 信封投影到 { "execution_id": "...", "status": "..." }，并在作用域数据可用时包含 openInHarness 执行链接。

如果 Harness 拒绝运行并提示未启用，请检查账户级的“允许动态执行”设置以及流水线 -> 高级选项 -> 动态执行设置下的流水线级开关。

执行输入取证

在运行后使用 execution_inputs 检查生成特定执行的合并输入 YAML。当失败取决于输入集合并、Git 支持的输入集分支或难以仅从执行页面重建的触发器/运行时值时，这非常有用。

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

获取响应被投影到：

executionId - 来自 resource_id 的计划执行 ID。
inputSetYaml - 用于运行的合并运行时输入 YAML，或 null。
inputSetTemplateYaml - 执行时的输入模板，或 null。
resolvedYaml - 当 resolve_expressions=true 时，表达式解析的 YAML，否则通常为 null。
inputSetDetails - 作为 { identifier, name } 对的贡献保存的输入集。
inputSetBranchName - Git 支持的输入集的源分支，或 null。

execution_inputs 是只读且风险较低的。如果省略 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 和重新检查提示。除非您已确认第一次执行未在运行，否则不要盲目重新运行流水线。
失败的终止状态包括指向 harness_diagnose(resource_type="execution", options={execution_id: "..."}) 的 _diagnose_hint。

让 AI DevOps 代理创建流水线：

{
  "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"
}

资源类型

255 种资源类型分布在 41 个工具集中。每种资源类型支持 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`

当流水线工具集启用时，两种流水线 YAML 资源类型都可用。HARNESS_PIPELINE_VERSION 和 HTTP x-harness-pipeline-version 初始化标头选择默认版本偏好；它们不会隐藏其他版本。

AI 代理

资源类型	列表	获取	创建	更新	删除	执行操作
`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

基础设施

资源类型	列表	获取	创建	更新	删除	执行操作
`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 列表返回引用处的所有路径；获取返回文件或目录内容（省略或传递空的 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"})

Multipart 主体约束：

创建/更新接受 JSON body，然后将其转换为 multipart/form-data 以用于 /ng/api/file-store。
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）或完整的 FileStoreNode body，包含 identifier、name 和 type: "FOLDER"。完整主体使用 Harness 驼峰命名法 parentIdentifier；简写形式可以使用 params.parent_identifier。

模板

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

模板操作使用 Harness 模板服务路径（/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，需要确认（征询或 confirm: true）。

变量集和提供者注册表的 RBAC（iac_variableset_*、iac_providerregistry_*）目前在 Harness 中为实验性——在 iac-server 启用强制执行之前，访问检查始终允许。模块注册表 RBAC（iac_registry_view / iac_registry_edit）为活跃且可强制执行。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

典型工作流程：

harness_list(resource_type="iacm_workspace", org_id="...", project_id="...") 查找工作区。
在 iacm_workspace 上执行 harness_create / harness_update，从零开始或从模板（associated_template）创建，或更新现有工作区——响应仅为 { policy_evaluation }。
harness_get(resource_type="iacm_workspace", workspace_id="...") 获取已创建/更新的工作区。
在 iacm_variable_set 上执行 harness_list / harness_create / harness_update（可选带 resource_scope）处理可重用的 Terraform/env 变量集——响应为 VariableSet 资源。
在 iacm_module 上执行 harness_list / harness_create / harness_update 处理模块注册表（name + system 必需；添加 resource_scope 及 org_id/project_id 以处理组织或项目范围的模块）——响应为模块资源。
在 iacm_provider 上执行 harness_list / harness_create / harness_update 处理账户提供者注册表（创建时需要 body.type；创建仅返回 { id }——然后执行 harness_get；更新仅创建/更新版本）——版本更新可能返回空成功。
harness_list(resource_type="iacm_resource", org_id="...", project_id="...", workspace_id="...") 检查 Terraform 资源、输出和数据源。
harness_list(resource_type="iacm_workspace_costs", org_id="...", project_id="...", workspace_id="...") 查看每次执行的成本条目。
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
`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 进行评论写入操作。

发布管理

发布管理（RMG）资源默认启用。定义资源（release_process、release_activity）支持列表/获取/创建/更新/删除，使用 body.yaml；在创建/更新前调用 harness_schema(resource_type="release_process"|"release_activity")。执行资源监控正在运行的发布——大多数列表操作需要 release_id（来自 harness_list resource_type=release 的 UUID，或 UI URL 片段，如 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 仅支持列表——在调用 harness_get 处理阶段输入/输出资源时，使用每个阶段项的 identifier 字段作为 params.phase_identifier（不要对 release_execution_phase 本身调用 harness_get）。发布列表 status 过滤仅在当前页面上客户端应用；当结果可能跨页面时，使用相同过滤器继续分页。

资源类型	列表	获取	创建	更新	删除
`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

典型工作流程：

使用 harness_list(resource_type="release_process", org_id="...", project_id="...") 发现编排流程定义。
在创建/更新之前使用 harness_schema(resource_type="release_process")（或 release_activity）；然后使用 harness_create / harness_update 配合 body.yaml。
使用 harness_list(resource_type="release", org_id="...", project_id="...") 查找活跃或最近的发布（默认回看 30 天；可选参数 filters.status、filters.search_term、filters.days_back）。
使用 harness_get(resource_type="release", release_id="...") 获取发布详情。
使用 harness_list(resource_type="release_execution_phase", filters={ release_id: "..." }) 获取阶段状态；相同的 release_id 用于 release_execution_task 和 release_execution_activity。
对 release_input、release_execution_phase_input、release_execution_phase_output、release_execution_activity_output 或 release_execution_activity_input 使用 harness_get，配合 release_id 以及 params.phase_identifier / params.activity_identifier / activity_execution_id，具体用法见各资源文档。

风格

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

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

API 支持两种接入路径。请保留这些 API 原生的请求格式：

编码代理可用的来源	API 流程
GitHub 仓库链接/连接器	使用 `harness_create`，配合 `resource_type="vibe_project"` 和 `body.mode` 以及模式特定字段。契约中命名为 `github_link` 和 `github_connector`，但未定义其 URL、分支或连接器字段格式；这些字段会原样转发到后端，不自行发明映射。
ZIP 文件	调用 `prepare` 并传入应用名称和文件元数据，将字节上传到返回的签名目标，然后调用 `deploy`。
本地源码目录	编码代理将目标工作区源码在本地打包为 ZIP，然后遵循 ZIP 流程。本地路径或对话上下文不是 API 支持的源码上传方式。

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

对于现有的 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 为准。准备操作返回 projectId、sourceId 和 upload，包括每个文件的 uploadUrl、method、headers 和 expiresAt。使用该签名 URL、方法和请求头直接上传文件字节；请原样保留 URL，不要向存储请求添加 Harness 凭据。准备操作不会读取或上传本地文件。

上传成功后，显式部署：

{
  "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，即使准备操作返回的是 camelCase 的 projectId。通用工具的顶层 project_id 是 Harness 作用域标识符，绝不作为 Vibe 应用 ID 使用。导入和准备会创建应用/源码；两者都不会启动部署。写入操作不会自动重试，部署使用现有的高风险确认策略。

使用 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）并关闭流。初始连接失败和流中断都不会重试。事件是瞬态差异，没有文档化的重放游标；请使用生命周期获取作为权威快照。两种生命周期读取在只读模式下均可用。

功能开关

资源类型	列表	获取	创建	更新	删除	执行操作
`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（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} 发送合并补丁；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。）Harness 原生模式在每个操作上均被拒绝（list/get/create/delete）— 请改用 fme_segment；此资源仅支持旧版 workspace_id 契约。
fme_rule_based_segment_definition —（已弃用 — 参见 fme_segment_definition。）Harness 原生模式在每个操作/动作上均被拒绝（list/update/enable/disable/change_request）— 请改用 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。更新仅限描述。当键仍存在时，删除会失败并返回 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 天内有事件的事件类型可见；get 对请求工作区流量类型范围之外或空闲超过 30 天的事件类型返回 404。列表过滤器：name（子字符串）、traffic_type（按 ID 或名称）、offset/limit（harness_list size 映射到 limit）。使用此资源发现真实的事件类型 ID，然后再在 fme_metric 的 baseEventTypes/filterEventType 或 event_type_ids 过滤器中引用，而不是猜测 ID。

在单用户/自托管模式下，旧版模式认证使用来自 HARNESS_FME_API_KEY 的 Bearer 令牌，回退到非占位符的 HARNESS_API_KEY。HARNESS_FME_API_KEY 可以是旧版 Split 管理员密钥或具有 FME 授权的 Harness PAT/SAT，但在 multi-user 模式下会被拒绝，因此共享部署不能覆盖每个会话用户的凭据。托管 OAuth/服务路由凭据用于 Harness 平台 API，不能认证直接的 Split.io 请求。fme_feature_flag 支持旧版模式下的完整生命周期管理：创建（需要 traffic_type_id）、列表、获取、更新元数据、删除，以及 kill/restore/reallocate/archive/unarchive 执行动作。使用 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_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

混沌工程

资源类型	列表	获取	创建	更新	删除	执行操作
`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`
`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
`chaos_risk_scan`	x	x	x	x	x	`retry`, `abort`, `report`, `report_download`, `heatmap`

云成本管理（CCM）

资源类型	列表	获取	创建	更新	删除	执行操作
`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、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

证据库

证据库存储 in-toto 证明（SDLC 证据）。列表支持通过 resource_scope 按账户/组织/项目范围进行筛选。单一自由文本筛选器（单独使用流水线、制品或 gitoid）使用 search_term；额外的名称约束使用 filters.subject_name；主题内容摘要使用 filters.subject_digest。获取通过 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 提升端点。当省略时，服务器从经过身份验证的用户自动填充 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

部署冻结

资源类型	列表	获取	创建	更新	删除	执行操作
`freeze_window`	x	x	x	x	x	`toggle_status`
`global_freeze`		x				`manage`

服务覆盖

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

设置

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

MCP 提示词

DevOps

Prompt	Description	Parameters
`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` 获取阶段/步骤明细、失败详情、代理信息和失败步骤日志，然后提供根因分析和修复建议。自动跟踪链式流水线失败。	`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.uses` 与旧版 `agent.step.group.steps` 规范格式），收集需求，以适当格式生成代理规范，与用户确认，然后通过 `harness_create`/`harness_update` 创建或更新	`agent_name`（必填）、`task_description`（必填）、`org_id`（可选）、`project_id`（可选）
`onboard-service`	引导新服务完成环境与部署流水线的接入流程	`serviceName`（必填）、`projectId`（可选）
`dora-metrics-review`	审查 DORA 指标（部署频率、变更失败率、MTTR、交付周期），提供精英/高/中/低分级及改进建议	`teamRefId`（可选）、`dateStart`（可选）、`dateEnd`（可选）
`setup-gitops-application`	引导完成 GitOps 应用接入——验证代理、集群、仓库，并创建应用	`agentId`（必填）、`projectId`（可选）
`chaos-resilience-test`	设计混沌实验以测试服务韧性，包括故障注入、探针和预期结果	`serviceName`（必填）、`projectId`（可选）
`feature-flag-rollout`	规划并执行跨环境的渐进式功能开关发布，并设置安全门控	`flagIdentifier`（必填）、`projectId`（可选）
`migrate-pipeline-to-template`	分析现有流水线并从中提取可复用的阶段/步骤模板	`pipelineId`（必填）、`projectId`（可选）
`delegate-health-check`	检查代理连接、健康状态、令牌状态，并排查基础设施问题	`projectId`（可选）
`developer-portal-scorecard`	审查服务的 IDP 记分卡，识别改进开发者体验的差距	`projectId`（可选）
`pending-approvals`	查找等待审批的流水线执行，显示详情，并提供批准或拒绝选项	`projectId`（可选）、`orgId`（可选）、`pipelineId`（可选）

FinOps

Prompt	Description	Parameters
`optimize-costs`	分析云成本数据，按潜在节省额优先展示建议和异常情况	`projectId`（可选）
`cloud-cost-breakdown`	按服务、环境或集群深入分析云成本，包含趋势分析和异常检测	`perspectiveId`（可选）、`projectId`（可选）
`commitment-utilization-review`	分析预留实例和节省计划利用率，发现浪费并优化承诺	`projectId`（可选）
`cost-anomaly-investigation`	调查成本异常——确定根因、受影响资源和修复措施	`projectId`（可选）
`rightsizing-recommendations`	审查并优先处理容量调整建议，可选择创建 Jira 或 ServiceNow 工单	`projectId`（可选）、`minSavings`（可选）

DevSecOps

Prompt	Description	Parameters
`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

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

MCP 资源

资源 URI	描述	MIME 类型
`pipeline:///{pipelineId}`	流水线 YAML 定义	`application/x-yaml`
`pipeline:///{orgId}/{projectId}/{pipelineId}`	流水线 YAML（带显式作用域）	`application/x-yaml`
`executions:///recent`	最近 10 条流水线执行摘要	`application/json`
`schema:///pipeline`	Harness 流水线 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 流水线 JSON Schema（简化的阶段/步骤格式）	`application/schema+json`
`schema:///agent-pipeline`	Harness AI 代理流水线 JSON Schema	`application/schema+json`
`agent-docs:///legacy-format`	旧版代理规范格式参考（`agent.step.group.steps` / `PLUGIN_TASK`），由 `create-agent` 提示在更新现有旧版格式代理时读取	`text/markdown`

工具集过滤

默认情况下，45 个工具集中的 41 个已启用。四个工具集为可选加入，默认排除：

ansible — Harness Ansible（清单、剧本、主机、活动）。可选加入，因为它按项目作用域划分，并引入了许多用户不需要的概念。
autonomous_work — 开发 Harness（自主工作）。可选加入；有关作用域，请参阅工具集描述。
observability-evaluations — 计划的生产遥测评估规则。可选加入，因为它依赖于已部署的评分控制平面。
registries-v3 — Harness 制品仓库 v3（包、版本、文件、元数据、扫描、防火墙例外）。可选加入，直到 v3 写入落地，这样代理就不必在 v1 仓库/制品和 v3 包/版本之间进行消歧。

使用 `+` 前缀添加工具集

使用 + 前缀显式包含可选加入的工具集以及所有默认工具集：

# 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
`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
`gitops`	gitops_agent, 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, 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_registry_item, eval_git_registration, online_eval
`observability-evaluations` (可选加入)	observability_evaluation_rule
`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

架构

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

工作原理

工具是通用动词：harness_list、harness_get 等。它们接受一个 resource_type 参数，用于路由到正确的 API 端点。
注册表将每个 resource_type 映射到一个 ResourceDefinition —— 一种声明式数据结构，指定 HTTP 方法、URL 路径、路径/查询参数映射以及响应提取逻辑。
调度解析资源定义，构建 HTTP 请求（路径替换、查询参数、resource_scope 感知的账户/组织/项目注入），通过 HarnessClient 调用 Harness API，并提取相关响应数据。
工具集过滤（HARNESS_TOOLSETS）控制启动时哪些资源定义被加载到注册表中。
结构化输出使用 MCP outputSchema 声明；harness_list 将数组和常见的列表包装器强制转换为对象形状的 structuredContent，以适配严格客户端。
深度链接自动附加到响应中，为每个资源提供直接的 Harness UI URL。
紧凑模式从列表结果中剥离冗长的元数据，仅保留可操作字段（身份、状态、类型、时间戳、深度链接），以最小化令牌使用量。

添加新的资源类型

在 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

引导确认（Elicitation）

写入工具（harness_create、harness_update、harness_delete、harness_execute）使用 MCP 引导确认在操作风险需要时提示用户确认 —— 仅限 medium_write、high_write 和 destructive 操作。低风险的创建/更新/读取（例如 pipeline.create、pipeline.update、hql_query.run）静默进行，不显示提示。当提示出现时，用户会看到即将执行的操作并选择接受或拒绝，为实际修改或运行的操作提供真正的人机协同审批。

工作原理：

LLM 调用一个风险等级为 medium_write+ 的写入工具（例如 harness_delete、harness_execute pipeline.run）。低风险的创建/更新/读取不会显示提示。
服务器向客户端发送引导确认请求，包含操作摘要和一个 confirm 复选框（默认勾选）。
用户查看详细信息并点击接受（勾选 confirm）或拒绝/取消。
如果勾选 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。当客户端无法显示提示或返回了退化接受（{action: "accept"} 缺少确认字段）时，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 搭配良好 —— 这是一组为常见 Harness 工作流设计的现成 Claude Code 技能（斜杠命令）。将它们与此 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` 创建新会话，然后使用新头重试
在 `/mcp` 上出现 HTTP `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`	用户拒绝或取消了确认对话框 — 具有权威性	与用户核实操作详情；`confirm: true` 不会绕过明确的拒绝。用户必须接受提示
`Operation blocked: the client could not surface a usable confirmation prompt`	客户端不支持确认功能，`elicitInput` 失败，或返回了退化的接受	对非交互式自动化使用 `confirm: true` 重试，或使用支持确认功能的客户端
模板创建/更新时出现 `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`

许可证

MIT

Harness

你可以用 Harness MCP 做什么？

文档

Harness MCP Server 2.0

为什么使用这个 MCP 服务器

前提条件

快速开始

选项 0：托管的 Harness MCP

选项 1：npx（推荐）

选项 2：全局安装

选项 3：从源码构建

Anthropic MCP 目录捆绑包

CLI 用法

HTTP 传输

HarnessID OAuth 模式

多用户模式

客户端配置

托管的 Harness MCP

Claude Desktop（claude_desktop_config.json）

Claude Code（通过 claude mcp add）

Cursor（.cursor/mcp.json）

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

MCP 网关

Docker MCP 网关

Portkey

LiteLLM

Envoy AI 网关

Kong

其他网关

Docker

Kubernetes

配置

语义搜索

HTTPS 强制

审计日志

工具参考

Schema 查找工作流

工具示例

流水线运行工作流（推荐）

动态流水线执行

执行输入取证

流水线执行等待模式

流水线存储模式

资源类型

平台

流水线

AI 代理

服务

环境

连接器

基础设施

密钥

执行日志

审计追踪

代理

代码仓库

制品仓库

文件存储

模板

仪表板

数据库 DevOps

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

内部开发者门户（IDP）

拉取请求

发布管理

风格

功能开关

GitOps

混沌工程

云成本管理（CCM）

软件工程洞察（SEI）

软件供应链保障（SCS）

证据库

安全测试编排（STO）

访问控制

治理

部署冻结

服务覆盖

设置

MCP 提示词

Claude Desktop（`claude_desktop_config.json`）

Claude Code（通过 `claude mcp add`）

Cursor（`.cursor/mcp.json`）

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

使用 `+` 前缀添加工具集