Harness

官方

存取並與 Harness 平台資料互動，包括管道、儲存庫、日誌及成品註冊表。

GitHub

試用此 MCP贊助

你可以用 Harness MCP 做什麼？

列出與檢查資源 — 請您的助理使用 harness_list 和 harness_get 探索組織、專案、管線或功能旗標，涵蓋 243 種資源類型。
跨專案執行監控 — 讓代理程式透過 harness_list 動態瀏覽帳戶階層，找出所有專案中失敗的管線執行。
建立與更新資源 — 使用 harness_create 和 harness_update，以自然語言佈建或修改服務、環境或其他 Harness 實體。
執行平台工作流程 — 利用 35 個內建的提示範本，除錯失敗的管線、檢視 DORA 指標、分類漏洞，或規劃功能旗標的逐步推出。
多使用者工作階段支援 — 在共用部署中，每個工作階段可使用各自的 x-harness-api-key 標頭進行驗證，讓稽核軌跡與實際使用者保持關聯。

文件

Harness MCP Server 2.0

一個 MCP（模型上下文協定）伺服器，透過 11 個整合工具和 243 種資源類型，讓 AI 代理程式能完整存取 Harness.io 平台。

為什麼使用這個 MCP 伺服器

大多數 MCP 伺服器將每個 API 端點對應到一個工具。對於像 Harness 這樣廣泛的平台，這意味著需要 240+ 個工具——而隨著工具數量增加，LLM 在工具選擇上的表現會變差。上下文視窗會被 schema 填滿，每個新端點都意味著新程式碼。

這個伺服器的建置方式不同：

11 個工具，243 種資源類型。 基於註冊表的派發系統將 harness_list、harness_get、harness_create 等路由到任何 Harness 資源——管線、服務、環境、組織、專案、功能旗標、成本資料等。LLM 只需從 11 個工具中選擇，而非數百個。
完整的平台涵蓋範圍。 40 個預設工具集，涵蓋 CI/CD、GitOps、功能旗標、雲端成本管理、安全測試、混沌工程、資料庫 DevOps、內部開發者入口網站、軟體供應鏈、基礎設施即程式碼管理、發布管理、治理、服務覆寫、知識圖譜等。當你需要庫存和 playbook 資料時，可選擇啟用 Ansible 涵蓋範圍。
開箱即用的多專案工作流程。 代理程式會動態探索組織和專案——無需硬編碼環境變數。詢問「顯示所有專案中失敗的執行」，代理程式就能導覽整個帳戶階層。
35 個提示詞範本。 為常見工作流程預先建置的提示詞：端到端建置與部署應用程式、除錯失敗的管線、檢視 DORA 指標、分類漏洞、最佳化雲端成本、稽核存取控制、規劃功能旗標發布、檢視 pull request、核准待處理的管線等。
隨處可用。 支援本機客戶端的 Stdio 傳輸（Claude Desktop、Cursor、Devin Desktop）、遠端/共享部署的 HTTP 傳輸，並已準備好 Docker 和 Kubernetes。
零設定啟動。 只需提供 Harness API 金鑰。帳戶 ID 會從 PAT 和 SAT 權杖自動擷取，組織/專案預設值為選用，工具集篩選可讓你只暴露需要的部分。
設計上可擴充。 新增 Harness 資源只需新增宣告式資料檔案——無需註冊新工具、無需變更 schema、無需更新提示詞。

前置需求

在安裝或執行伺服器之前，你需要一個 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 套件 manifest 位於 [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 端點（initialize + session 請求）
`/mcp`	`GET`	伺服器主動訊息（進度、徵詢）的 SSE 串流
`/mcp`	`DELETE`	終止作用中的 MCP session
`/mcp`	`OPTIONS`	CORS 預檢
`/health`	`GET`	健康檢查——回傳 `{ "status": "ok", "sessions": <count> }`

HTTP 傳輸以基於 session 的模式執行。新的 MCP session 會在 initialize 時建立，伺服器會回傳 mcp-session-id 標頭，該 session 的後續請求必須包含相同的標頭。

HTTP 模式下的營運限制：

任何共享或可遠端存取的部署都必須設定 HARNESS_MCP_AUTH_TOKEN。設定後，對 /mcp 的每個 POST、GET 和 DELETE 請求都必須包含 Authorization: Bearer <token>。
非 loopback 綁定預設需要 HARNESS_MCP_AUTH_TOKEN。若仍要在非 loopback 介面上以未驗證方式執行，請明確設定 HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP=true。
沒有 mcp-session-id 的 POST /mcp 必須是 initialize 請求。
既有 session 的 POST /mcp、GET /mcp 和 DELETE /mcp 需要 mcp-session-id 標頭。
GET /mcp 用於 SSE 通知（進度更新和徵詢提示）。
閒置 session 在沒有請求或 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 session 選擇 V0 或 V1 管線資源。
在 initialize 請求上設定 x-harness-auto-approve-risk: none|low_write|medium_write|high_write|all，可選擇更嚴格的每 session 自動核准閾值。伺服器會將此值上限設為部署層級的 HARNESS_AUTO_APPROVE_RISK，因此 session 可以降低但不能擴大設定的核准上限。

多使用者模式

對於每個用戶端以不同 Harness 使用者身分驗證的共享 HTTP 部署，請設定 HARNESS_MCP_MODE=multi-user。在此模式下：

伺服器設定中不得設定 HARNESS_API_KEY——伺服器不持有任何 Harness 憑證。
每個 session 必須在 initialize 請求上提供 x-harness-api-key。僅當 API 金鑰未內嵌帳戶區段時，才需要 x-harness-account-id。
Session 也可以提供 x-harness-org 和 x-harness-project 標頭，為該 session 設定預設範圍。
Harness API 金鑰會流經該 session 的每個 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 控制 Host 標頭驗證以進行 DNS rebinding 防護，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 伺服器提供集中式驗證、治理、工具路由和可觀測性。由於伺服器透過 stdio 和 HTTP 傳輸實作標準 MCP 協定，因此可在任何符合 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 個複本，具備就緒/存活探測、資源限制和非 root 安全內容。Service 在內部公開連接埠 80（目標為容器連接埠 3000）。

設定

如果專案根目錄中存在 .env 檔案，伺服器會自動從中載入環境變數。將 .env.example 複製為 .env 並填入您的值。環境變數也可以透過您的 shell 或 MCP 用戶端設定來設定。

變數	必填	預設值	說明
`HARNESS_MCP_MODE`	否	`single-user`	部署模式：`single-user`（API 金鑰位於設定檔中，用於所有工作階段）或 `multi-user`（僅限 HTTP，透過 `x-harness-api-key` 與選用的 `x-harness-account-id` 標頭提供每工作階段憑證）
`HARNESS_API_KEY`	是*	--	Harness 個人存取權杖或服務帳戶權杖。在 `single-user` 模式下為必填。在 `multi-user` 模式下不得設定
`HARNESS_ACCOUNT_ID`	否	(來自 PAT/SAT)	Harness 帳戶識別碼。在單一使用者模式下會從 PAT/SAT 權杖自動擷取；當 API 金鑰未內嵌帳戶識別碼時，多使用者工作階段可透過 `x-harness-account-id` 提供各自的帳戶識別碼
`HARNESS_BASE_URL`	否	`https://app.harness.io`	用於本機 stdio 或自架 HTTP 部署的 Harness API/UI 基礎 URL。當您自行執行伺服器時，請將其設定為 `https://harness0.harness.io` 等環境。此設定不影響受管理的 `https://mcp.harness.io/mcp` 託管端點
`HARNESS_FME_API_KEY`	否	--	選用的單一使用者/自架 FME/Split 管理員憑證，僅在舊版（`workspace_id`）模式下用於 `fme_` 資源。這可以是舊版 Split 管理員金鑰或具 FME 權限的 Harness PAT/SAT。FME 呼叫會直接前往 `api.split.io`，因此 Harness 平台 API 的託管 OAuth/服務路由憑證無法驗證這些請求。在 `multi-user` 模式下不得設定；FME 必須使用每個工作階段的 `x-harness-api-key` 憑證。若未設定，FME 會為自架工作階段回退至非佔位符的 `HARNESS_API_KEY`。Harness 原生（`org_id`+`project_id`）模式會忽略此設定，並改用標準的 `HARNESS_API_KEY`/`HARNESS_BASE_URL`
`HARNESS_FME_BASE_URL`	否	`https://api.split.io`	由 `fme_` 資源在舊版（`workspace_id`）模式下使用的 Split/FME 管理員 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`。代理程式也可以透過 `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` 以移除預設工具集（請參閱 Toolset Filtering）
`HARNESS_READ_ONLY`	否	`false`	封鎖所有變更操作（建立、更新、刪除、執行）。僅允許清單與取得。適用於共用/示範環境
`HARNESS_AUTO_APPROVE_RISK`	否	`none`	自主工作流程的風險基礎自動核准閾值。風險等於或低於此值的操作會直接執行，無需確認。值：`none`、`low_write`、`medium_write`、`high_write`、`all`。請參閱 Elicitation
`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` 預設允許用於 localhost 繫結；請在此新增代理/自訂網域
`HARNESS_MCP_AUTH_TOKEN`	否	--	設定後，`/mcp` HTTP 路由需要 Bearer 權杖。當 HTTP 傳輸繫結至非迴環主機時，預設為必填
`HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP`	否	`false`	明確允許在非迴環繫結上進行未驗證的 HTTP 傳輸。僅可在另一個已驗證的控制項後方使用
`HARNESS_MCP_TRUST_PROXY`	否	`0`	用於用戶端 IP 解析時信任的反向代理/負載平衡器跳數（Express `trust proxy`）。請設定為伺服器前方的代理數量，以便每個 IP 的速率限制以真實用戶端為依據，而非代理的 socket 對端
`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 稽核 spans
`HARNESS_SEARCH_PROVIDER`	否	`local`	語意搜尋後端：`local`（程序內 ONNX 嵌入，預設）、`remote`（透過 HTTP 的外部搜尋服務，多使用者模式必填）或 `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` 在擷取失敗步驟的日誌時發出的最大並行日誌區塊下載數。僅在診斷延遲主要由日誌擷取牆鐘時間主導且 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

使用內含的 stub 服務在本機測試遠端提供者（無需外部相依）：

# 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（stub-search-service.py）實作了與正式搜尋服務相同的 /v1/health、/v1/ingest 和 /v1/search 契約。它使用簡單的 bag-of-chars 嵌入，因此不需要下載模型——結果在語意上合理，但不具備正式品質。

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.

稽核日誌

所有由 registry 分派的 Harness API 操作（list、get、create、update、delete 和 execute）在設定稽核 sink 時都會發出結構化稽核事件。變更事件包含在存在確認上下文時，由 elicitation 或自動核准所使用的確認路徑；讀取事件目前省略確認中繼資料。繞過 registry 的本機中繼資料和 schema 探索工具（例如 harness_describe 和 harness_schema）不屬於此稽核串流的一部分。預設會註冊 stderr sink，但它會透過一般 logger 運作並遵循 LOG_LEVEL；請設定檔案或 webhook sink 以進行持久化稽核收集：

HARNESS_AUDIT_FILE 會附加換行分隔的 JSON 事件，供本機收集使用。
HARNESS_AUDIT_WEBHOOK_URL 會將 { "events": [...] } 批次發布到 HTTPS webhook，可選擇搭配 HARNESS_AUDIT_WEBHOOK_TOKEN。失敗的批次會以有限的容量重新排入佇列，最終會以警告方式丟棄，而不會阻擋工具執行。
OTEL_EXPORTER_OTLP_ENDPOINT 在安裝選用的 OpenTelemetry 同儕相依套件時啟用稽核 span。該 sink 在已註冊 tracer provider 時會重複使用現有的 provider，否則會自行啟動獨立的 OTLP exporter。

每個事件都包含工具名稱、資源類型、操作、識別碼、時間戳記、風險、結果、HTTP 方法／路徑、持續時間，以及在適用時的確認方法。稽核 sink 是盡力而為的遙測；傳遞問題會被記錄下來，絕不會重播或改變底層的 Harness API 操作。有關 OTel 設定詳細資訊和 span 屬性，請參閱 specs/005-otel-audit-sink.md。

工具參考

伺服器公開 11 個 MCP 工具。大多數 API 工具接受 org_id 和 project_id 作為選用覆寫——如果省略，則會回退到 HARNESS_ORG 和 HARNESS_PROJECT。harness_describe 僅限本機中繼資料，不使用 org／project 範圍。

URL 支援： 大多數面向 API 的工具接受 url 參數——貼上 Harness UI URL，伺服器會自動擷取 org、project、資源類型、資源 ID、pipeline ID 和執行 ID。harness_describe 不接受 url。

範圍支援： 具有 account／org／project 變體的資源類型會在 harness_describe 中公開 supportedScopes。當您需要特定層級時，請傳入 resource_scope：

resource_scope: "account" 僅傳送 accountIdentifier。
resource_scope: "org" 傳送 accountIdentifier 和 orgIdentifier。
resource_scope: "project" 傳送 account、org 和 project 識別碼。

目前的多範圍資源包括 connector、service、environment、infrastructure、secret、file_store、template、policy 和 policy_set。如果省略 resource_scope，registry 會使用資源的預設範圍和設定的預設值，但標記為選用範圍的資源可能會省略 org／project，除非明確傳入。當路徑包含 account 層級或 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/模板 schema 為內建；連接器、環境、服務、密鑰和基礎設施 schema 是具範圍感知的實體 schema，從內建快照或 NG `/yaml-schema` 擷取；`release_process` 和 `release_activity` schema 則從 RMG `/api/yamlSchema` 即時擷取。支援透過 `path` 進行深度鑽取。
`harness_list`	列出指定類型的資源，支援篩選、搜尋和分頁。
`harness_get`	依識別碼取得單一資源。
`harness_create`	建立新資源。支援內聯和遠端（Git 支援）的 pipeline。透過 elicitation 提示使用者確認。
`harness_update`	更新現有資源。支援內聯和遠端（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，回傳階段/步驟時間和失敗詳細資訊；對於連接器/委派/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 Management 定義（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" }

列出專案中的 pipeline：

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

取得特定服務：

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

執行 pipeline：

{
  "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 的最新執行報告：

{ "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 編寫 pipeline：

{ "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 pipeline，請使用此順序以減少執行時的輸入錯誤：

探索必要的執行時輸入

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

選擇輸入策略

簡單變數： 傳遞扁平鍵值 inputs（例如 {"branch":"main","env":"prod"}）。
複雜/結構化輸入： 使用 input_set_ids（CI codebase/建置區塊和巢狀模板輸入最適合以此方式處理）。

CI codebase 速記鍵（僅限 pipeline 執行）：

速記鍵	展開的結構
`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 支援 pipeline，請傳遞 params.pipeline_branch（以 pipelineBranchName 傳送至 Harness）：

{
  "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 pipeline：

擷取 harness_get(resource_type="runtime_input_template_v1", resource_id="<pipeline_id>")。對於 Git 支援的 pipeline，請透過 params 傳遞 branch_name、connector_ref 和 repo_name。
讀取 template_yaml 和 resolved_yaml 以取得宣告的 ${{ 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）檢查可用的速記對應。

動態 Pipeline 執行

當代理程式或外部系統在執行階段產生完整的 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。
執行階段的 <+input> 佔位符不會由此 API 解析。請提交已完整解析的 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"
}

資源類型

243 種資源類型，組織於 40 個工具集中。每種資源類型支援 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
`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				`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。

成品登錄

資源類型	列出	取得
`registry`	x	x
`artifact`	x
`artifact_version`	x
`artifact_file`	x

檔案存放區

資源類型	列出	取得	建立	更新	刪除	執行動作
`file_store`	x	x	x	x	x	`list_children`
`file_store` 透過通用工具管理 Harness File Store 檔案與資料夾。它支援帳戶、組織與專案範圍；請傳入 `resource_scope="account"	"org"	"project"` 或貼上 Harness File Store 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 camelCase 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——建議先取得再放入以處理選用欄位。寫入為 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/環境變數集——回應為 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="...") 以檢查 plan、apply 或 destroy 活動的資源前後差異。

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
`pr_check`	x
`pr_activity`	x

使用 harness_execute(resource_type="pull_request", action="close", ...) 進行明確的關閉操作。harness_update 也接受 body.state（open 或 closed），並將狀態變更路由到專用的 Harness Code PR 狀態端點；請在單獨的更新呼叫中傳送標題/描述編輯。

發行管理

發行管理（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，如各資源文件所述。

功能旗標

資源類型	列表	取得	建立	更新	刪除	執行動作
`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
`fme_segment_definition`	x	x	x	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 原生模式的涵蓋範圍目前較窄：

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 發送 merge-patch 至 /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 上的動作相同。取得/建立/更新請求體與舊版相符（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 —（已棄用——請參閱 fme_segment。）Harness 原生模式在每個操作上皆被拒絕（list/get）——請改用 fme_segment；此資源僅支援舊版 workspace_id 契約。此資源在任一模式下皆沒有 create 操作。
fme_segment_keys — 若同時傳入 org_id+project_id，則 list/update 尚未實作；否則視為一般舊版呼叫進行。
fme_segment — list/get/create/delete 已接線至真實的 /fme/api/v4/segments 端點（整合 fme_standard_segment/fme_rule_based_segment）；create 請求體：name、trafficType、type（必填——standard/rule_based/large 其中之一）、可選的 description/tags/owners。
fme_segment_definition — 僅限 Harness 原生（不支援舊版 workspace_id）。list/get/create/update/delete 已接線至 /fme/api/v4/segment-definitions，依 Harness_Split/Main PR #12644（截至撰寫本文時為開啟狀態，尚未合併——路徑可能仍會變更）。update 在 description 上使用 JSON Merge Patch，這是唯一可變的欄位。沒有 enable/disable/change_request 動作——後端對這個統一資源沒有此類端點。

在單一使用者/自架模式中，舊版模式驗證使用來自 HARNESS_FME_API_KEY 的 Bearer token，若無則回退至非佔位符的 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/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_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

混沌工程

資源類型	列表	取得	建立	更新	刪除	執行動作
`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

軟體工程洞察（SEI）

SEI 資源已整合以提升 token 效率。請使用 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 指定帳戶/組織/專案範圍。單一自由文字篩選器（pipeline、artifact 單獨使用、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
`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 代理——檢查既有代理、收集需求、使用代理管線結構描述產生代理 YAML 規格、與使用者確認，然後透過 `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}`	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 template JSON Schema	`application/schema+json`
`schema:///trigger`	Harness trigger JSON Schema	`application/schema+json`
`schema:///pipeline_v1` (Alpha)	Harness V1 pipeline JSON Schema（簡化 stages/steps 格式）	`application/schema+json`
`schema:///agent-pipeline`	Harness AI agent pipeline JSON Schema	`application/schema+json`

工具集篩選

預設情況下，40 個工具集中的 41 個已啟用。一個工具集是選擇加入的，並從預設值中排除：

ansible — Harness Ansible（inventories、playbooks、hosts、activity）。選擇加入，因為它是專案範圍的，並增加了許多使用者不需要的概念。

使用 `+` 前綴新增工具集

使用 + 前綴，以在預設值之外明確包含選擇加入的工具集：

# 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
`gitops`	gitops_agent, 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
`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
`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
`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
`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

架構

                 +------------------+
                 |   AI Agent       |
                 |  (Claude, etc.)  |
                 +--------+---------+
                          |  MCP (stdio or HTTP)
                 +--------v---------+
                |    MCP Server     |
                | 11 Generic Tools  |
                 +--------+---------+
                          |
                 +--------v---------+
                |    Registry       |  <-- Declarative resource definitions
                |  40 Toolsets      |      (data files, not code)
                |  243 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。
精簡模式會從列表結果中移除冗長的中繼資料，僅保留可操作的欄位（身分、狀態、類型、時間戳、深層連結），以最小化 token 使用量。

新增資源類型

在 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）會靜默執行，不顯示提示。當顯示提示時，使用者會看到即將執行的操作並選擇接受或拒絕，為實際變更或執行事物的操作提供真正的人員介入核准。

運作方式：

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`（schema 的預設值）接受時才繼續。明確拒絕、取消或接受但未勾選 `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: true 未包含確認欄位）時，{action: "accept"} 會作為後備方案被採用，但它不會覆蓋已完成引導確認交握的用戶端所做出的明確拒絕/取消。

自主模式

自主模式表示伺服器會繼續執行所有操作——包括寫入和破壞性動作——而不提示確認。透過設定以下項目來啟用：

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 key 不是受支援的帳戶範圍格式（`pat.<accountId>...` 或 `sat.<accountId>...`），因此無法推斷帳戶 ID	明確設定 `HARNESS_ACCOUNT_ID`
啟動時出現 `Unknown transport: "..."`	不支援的 CLI 傳輸參數	僅使用 `stdio` 或 `http`
啟動時出現 `Invalid HARNESS_TOOLSETS: ...`	一個或多個工具集名稱無法辨識	僅使用 Toolset Filtering 中的名稱（完全相符）
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 `405 Method Not Allowed` 於 `/mcp`	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`
Pipeline 執行在預檢階段因未解析的必要輸入而失敗	提供的 `inputs` 未涵蓋必要的執行時期佔位符	取得 `runtime_input_template`、提供缺少的簡單鍵，或對結構化輸入使用 `input_set_ids`
Pipeline CI 簡寫（`branch`、`tag`、`pr_number`、`commit_sha`）未生效	已提供 `inputs.build`，因此刻意跳過簡寫展開	移除 `inputs.build` 以使用簡寫展開，或保留完整的明確 `build` 結構
Pipeline 執行載入錯誤的 YAML 修訂版本	Pipeline 定義儲存在 Git 中，且執行未指定所需的 pipeline 分支	在 `run` 動作上傳遞 `params.pipeline_branch`；這對應於 Harness `pipelineBranchName`
`wait: true` 回傳 `_wait.error`	Pipeline 觸發成功，但伺服器端輪詢失敗	在決定是否重新執行前，使用 `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 傳輸

多使用者模式

用戶端設定

託管式 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 查詢工作流程

工具範例

Pipeline 執行工作流程（建議）

動態 Pipeline 執行

執行輸入鑑識

管線執行等待模式

管線儲存模式

資源類型

平台

管線

AI 代理程式

服務

環境

連接器

基礎設施

密碼

執行日誌

稽核軌跡

委派者

程式碼儲存庫

成品登錄

檔案存放區

範本

儀表板

資料庫 DevOps

基礎設施即程式碼管理（IaCM）

內部開發者入口網站（IDP）

拉取請求

發行管理

功能旗標

GitOps

混沌工程

雲端成本管理（CCM）

軟體工程洞察（SEI）

軟體供應鏈保證（SCS）

證據庫

安全測試編排（STO）

存取控制

治理

部署凍結

服務覆寫

設定

MCP 提示詞

DevOps

FinOps

Claude Desktop（`claude_desktop_config.json`）

Claude Code（透過 `claude mcp add`）

Cursor（`.cursor/mcp.json`）

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

使用 `+` 前綴新增工具集