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 Toplist

一個 MCP（Model Context Protocol）伺服器，讓 AI 代理程式透過 11 個整合工具和 255 種資源類型，完整存取 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 資源只需新增一個宣告式資料檔案——無需註冊新工具、無需變更 schema、無需更新提示詞。

先決條件

在安裝或執行伺服器之前，您需要一個 Harness API 金鑰：

  1. 登入您的 Harness 帳戶
  2. 前往 我的個人資料 → API 金鑰 → + 新增 API 金鑰
  3. 在 API 金鑰下建立一個新的 權杖——這會產生格式為 <prefix>.<accountId>.<tokenId>.<secret> 的 PAT 或 SAT
  4. 將權杖儲存在安全的地方——下一步會用到

如需詳細說明，請參閱 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 的扁平佈局從 npm-shrinkwrap.json 安裝生產依賴項。固定版本的官方 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 模式下執行時，伺服器會暴露：

端點方法說明
/mcpPOSTMCP JSON-RPC 端點（initialize + session 請求）
/mcpGET伺服器主動訊息（進度、誘發）的 SSE 串流
/mcpDELETE終止作用中的 MCP session
/mcpOPTIONSCORS 預檢
/healthGET健康檢查——回傳 { "status": "ok", "sessions": <count> }
/.well-known/oauth-protected-resourceGET當 HARNESS_MCP_MODE=oauth 時的 RFC 9728 中繼資料
/.well-known/oauth-protected-resource/mcpGET預設 /mcp 資源的路徑感知 RFC 9728 中繼資料

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

HTTP 模式下的操作限制：

  • 為共享或可遠端存取的單一使用者及多使用者部署設定 HARNESS_MCP_AUTH_TOKEN。設定後，每個對 /mcp 的 POST、GET 和 DELETE 請求都必須包含 Authorization: Bearer <token>。
  • OAuth 模式接受 HarnessID 存取權杖而非 HARNESS_MCP_AUTH_TOKEN，且可在沒有未驗證退出選項的情況下綁定到非 loopback 位址。
  • 非 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 可以降低但不能擴大設定的核准上限。

HarnessID OAuth 模式

設定 HARNESS_MCP_MODE=oauth 以讓遠端 MCP 用戶端探索 HarnessID 並完成 OAuth 2.1 Authorization Code with PKCE。OAuth 模式僅在 HTTP 傳輸下可用。生產環境的 HarnessID、MCP 資源和 API 路由預設值已內建：

HARNESS_MCP_MODE=oauth

這預設為 issuer https://id.harness.io/idp/realms/HarnessIDP、resource https://mcp.harness.io/mcp、OAuth client mcp-client 和 Harness API base 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 受保護資源中繼資料，並在用戶端尚未驗證時回傳此 challenge：

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 claim 檢查權杖是否簽發給 HARNESS_MCP_OAUTH_CLIENT_ID。HARNESS_MCP_OAUTH_RESOURCE 是用於探索和 challenge 的 RFC 9728 受保護資源識別碼。目前的 HarnessID 存取權杖使用 aud: account 而非 MCP URL，因此不會將資源與 aud 比較。

帳戶 ID 來自權杖的 HARNESS_MCP_OAUTH_ACCOUNT_CLAIM claim（預設為 account_id），由 HarnessID 的 organization scope 填入。每個 session 會儲存呼叫者的存取權杖，並以 Authorization: Bearer 轉發到 Harness API，因此 Harness RBAC 和稽核記錄反映的是登入使用者，而非共享的 PAT。session 綁定到建立時的 sub 和帳戶：後續請求可能攜帶重新整理的權杖，但屬於不同使用者或帳戶的權杖會被拒絕。

用戶端通常只需要 MCP 資源 URL：

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

用戶端會讀取受保護資源中繼資料、探索 HARNESS_MCP_OAUTH_ISSUER，然後使用該授權伺服器的 RFC 8414 中繼資料。如果用戶端不支援動態用戶端註冊，請使用預先註冊的 mcp-client 用戶端 ID。

請參閱 自架 MCP 伺服器的 HarnessID OAuth 取得 QA Keycloak 檢查清單和驗證指令。

多使用者模式

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

  • 伺服器設定中不得設定 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 重新綁定防護，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 Platform 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 Gateway、IBM ContextForge、Cloudflare Workers 等）都可以代理此伺服器。對於基於 stdio 的閘道，請使用預設傳輸。對於基於 HTTP 的閘道，請使用 http 傳輸啟動伺服器，並將閘道指向 /mcp 端點。

Docker

將伺服器建置並執行為 Docker 容器：

# Build the image
pnpm docker:build

# Run with your .env file
pnpm docker:run

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

容器預設以 HTTP 模式在連接埠 3000 上執行，並內建健康檢查。

Kubernetes

使用提供的清單部署到 Kubernetes 叢集：

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

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

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

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

部署會執行 2 個複本，並配備就緒/存活探測、資源限制和非 root 安全性內容。Service 在內部公開連接埠 80（目標為容器連接埠 3000）。

設定

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

變數必填預設值說明
HARNESS_MCP_MODE否single-user部署模式：single-user（共用 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 金鑰未內嵌帳戶識別碼時，透過 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/HarnessIDPHarnessID 簽發者，會與存取權杖的 iss 宣告進行精確比對
HARNESS_MCP_OAUTH_RESOURCE否https://mcp.harness.io/mcp公開的標準 MCP URL，發布為 RFC 9728 資源識別碼
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.ioSplit/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否30000HTTP 請求逾時時間（毫秒）
HARNESS_MAX_RETRIES否3暫時性失敗（429、5xx）的重試次數
HARNESS_MAX_BODY_SIZE_MB否10http 傳輸的 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） 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 權杖。非迴圈位址的單一使用者和多使用者繫結預設為必填。在 oauth 模式下必須取消設定
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否10Webhook 重新整理前要批次處理的稽核事件數
HARNESS_AUDIT_WEBHOOK_FLUSH_MS否5000Webhook 刷新前保留審計事件的最長時間
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用於 local 搜尋提供者所使用的 @huggingface/transformers 模型快取目錄。Docker 映像已將模型預先烘焙至 /app/.cache/hf 以避免執行時下載。在生產部署中，請設定為持久化磁碟區路徑
HARNESS_DIAGNOSE_LOG_FETCH_CONCURRENCY否3harness_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）都會發出結構化稽核事件。變更事件包含在存在確認上下文時，由 elicitation 或自動核准使用的確認路徑；讀取事件目前省略確認中繼資料。繞過 registry 的本機中繼資料和 schema 探索工具（例如 harness_describe 和 harness_schema）不屬於此稽核串流的一部分。預設會註冊 stderr 接收器，但它會透過一般 logger 運作並遵循 LOG_LEVEL；請設定檔案或 webhook 接收器以進行持久化稽核收集：

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

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

工具參考

伺服器公開 11 個 MCP 工具。大多數 API 工具接受 org_id 和 project_id 作為選用覆寫 — 如果省略，則會回退到 HARNESS_ORG 和 HARNESS_PROJECT。harness_describe 僅限本機中繼資料，不使用 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，請使用此順序以減少執行時輸入錯誤：

  1. 探索必要的執行時輸入
  • harness_get(resource_type="runtime_input_template", resource_id="<pipeline_id>")
  • 回傳的模板顯示需要值的 <+input> 佔位符。
  1. 選擇輸入策略

  • 簡單變數： 傳入扁平鍵值 inputs（例如 {"branch":"main","env":"prod"}）。

  • 複雜/結構化輸入： 使用 input_set_ids（CI codebase/建置區塊和巢狀模板輸入最適合以此方式處理）。

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

    速記鍵展開結構
    branchbuild.type=branch、build.spec.branch=<value>
    tagbuild.type=tag、build.spec.tag=<value>
    pr_numberbuild.type=PR、build.spec.number=<value>
    commit_shabuild.type=commitSha、build.spec.commitSha=<value>

  • 約束： 當 inputs.build 已存在時，會跳過速記展開（明確的 build 優先）。

  1. 執行執行

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

  • 對於應從非預設分支載入 YAML 的 Git 支援 pipeline，請傳入 params.pipeline_branch（以 branch 傳送至 Harness）。此明確的定義選擇器優先於 params.branch 別名。inputs.branch 獨立選擇 CI codebase 分支：

    {
  "resource_type": "pipeline",
  "action": "run",
  "resource_id": "deploy_app",
  "params": { "pipeline_branch": "feature/new-stage" },
  "inputs": { "branch": "main" },
  "wait": true
}
  1. 可選：兩者結合
  • 使用 input_set_ids 作為基礎形狀，並使用 inputs 進行簡單覆寫。

對於 v1 pipeline：

  1. 取得 harness_get(resource_type="runtime_input_template_v1", resource_id="<pipeline_id>")。 對於 Git 支援的 pipeline，請透過 params 傳入 branch_name、connector_ref 和 repo_name。
  2. 將每個回傳的 inputs[].details.name 用作 harness_execute.inputs 中的頂層鍵。
  3. 執行 harness_execute(resource_type="pipeline_v1", action="run", resource_id="<pipeline_id>", inputs={...})。 伺服器將這些值包裝在 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 與重新檢查提示。除非您已確認第一次執行未在執行中，否則請勿盲目重新執行管線。
  • 失敗的終端狀態包含 _diagnose_hint，指向 harness_diagnose(resource_type="execution", options={execution_id: "..."})。

要求 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 操作的子集與選用的執行動作。

平台

資源類型列出取得建立更新刪除執行動作
organizationxxxxx
projectxxxxx

管線

資源類型列出取得建立更新刪除執行動作
pipelinexxxxxrun、retry
pipeline_v1 （Alpha）xxxxxrun
pipeline_dynamic_executionrun
executionxxinterrupt
execution_inputsx
triggerxxxxx
pipeline_summaryx
input_setxxxxx
runtime_input_templatex
runtime_input_template_v1x
pipeline_resolved_yamlx
approval_instancexapprove、reject

當管線工具集啟用時，兩種管線 YAML 資源類型皆可用。HARNESS_PIPELINE_VERSION 與 HTTP x-harness-pipeline-version 初始化標頭會選取預設版本偏好；它們不會隱藏其他版本。

AI 代理程式

資源類型列出取得建立更新刪除執行動作
agentxxxxx
agent_runx

服務

資源類型列出取得建立更新刪除執行動作
servicexxxxx

環境

資源類型列出取得建立更新刪除執行動作
environmentxxxxxmove_configs

連接器

資源類型列出取得建立更新刪除執行動作
connectorxxxxxtest_connection
connector_cataloguex

基礎設施

資源類型列出取得建立更新刪除執行動作
infrastructurexxxxxmove_configs

密碼

資源類型列出取得建立更新刪除執行動作
secretxx

執行日誌

資源類型列出取得建立更新刪除執行動作
execution_logx

稽核軌跡

資源類型列出取得建立更新刪除執行動作
audit_eventxx

委派者

資源類型列出取得建立更新刪除執行動作
delegatexx
delegate_tokenxxxxrevoke、get_delegates

程式碼儲存庫

資源類型列出取得建立更新刪除執行動作
repositoryxxxx
branchxxxx
commitxxxdiff、diff_stats
file_contentxxblame
tagxxx
repo_rulexx
space_rulexx

commit 建立會直接透過 Harness Code API 提交一個或多個檔案動作，而不需複製。傳入 body.title、body.branch 與 body.actions；每個動作是 CREATE、UPDATE、DELETE 或 MOVE，且 UPDATE 需要目前的 blob SHA。

file_content 列出會回傳 ref 上的每個路徑；取得會回傳檔案或目錄內容（省略或傳入空的 path 以取得儲存庫根目錄；巢狀路徑保留斜線）。省略 git_ref 以使用儲存庫預設分支 — 請勿猜測 main。

成品登錄

資源類型列表取得建立更新刪除執行操作
registryxx
artifactx
artifact_versionx
artifact_filex

檔案存放庫

資源類型列表取得建立更新刪除執行操作
file_storexxxxxlist_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 的 camelCase parentIdentifier；簡寫可使用 params.parent_identifier。

範本

資源類型列表取得建立更新刪除執行操作
templatexxxxx

範本操作使用 Harness 範本服務路徑（/template/api/templates...）。建立與更新需要在 body.template_yaml 或 body.yaml 中提供完整的範本 YAML 字串；version_label 針對特定版本進行更新/刪除，而刪除時若未提供 version_label 則刪除所有版本。

儀表板

資源類型列表取得建立更新刪除執行操作
dashboardxx
dashboard_datax

資料庫 DevOps

資源類型列表取得建立更新刪除執行操作
database_schemaxxxxx
database_instancexxxxx
database_snapshot_objectxx
database_llm_authoring_pipelinex

基礎設施即程式碼管理（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_workspacexxxx
iacm_variable_setxxxx
iacm_resourcex
iacm_modulexxxx
iacm_providerxxxx
iacm_workspace_costsx
iacm_activity_resource_changex

典型工作流程：

  1. harness_list(resource_type="iacm_workspace", org_id="...", project_id="...") 尋找工作區。
  2. 在 iacm_workspace 上使用 harness_create / harness_update 從零開始或從範本（associated_template）建立，或更新現有工作區——回應僅為 { policy_evaluation }。
  3. harness_get(resource_type="iacm_workspace", workspace_id="...") 取得已建立/更新的工作區。
  4. 在 iacm_variable_set 上使用 harness_list / harness_create / harness_update（可選用 resource_scope）取得可重複使用的 Terraform/env 變數集——回應為 VariableSet 資源。
  5. 在 iacm_module 上使用 harness_list / harness_create / harness_update 存取模組登錄（name + system 為必填；加上 resource_scope 與 org_id/project_id 以取得組織或專案範圍的模組）——回應為模組資源。
  6. 在 iacm_provider 上使用 harness_list / harness_create / harness_update 存取帳戶提供者登錄（建立時 body.type 為必填；建立僅回傳 { id }——然後 harness_get；更新僅建立/更新版本）——版本更新可能回傳空成功。
  7. harness_list(resource_type="iacm_resource", org_id="...", project_id="...", workspace_id="...") 檢查 Terraform 資源、輸出與資料來源。
  8. harness_list(resource_type="iacm_workspace_costs", org_id="...", project_id="...", workspace_id="...") 檢視每次執行的成本項目。
  9. harness_list(resource_type="iacm_activity_resource_change", org_id="...", project_id="...", activity_id="...", workspace_id="...") 檢查計畫、套用或銷毀活動的資源前後差異。

IaCM 列表回應將 page_count 暴露為僅目前頁面的計數（iacm_variable_set 除外，它不分頁）。當 has_more 為 true 時，持續請求下一個以 1 為基礎的頁面，並在需要總數時加總頁面計數。

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

資源類型列表取得建立更新刪除執行操作
idp_entityxx
scorecardxx
scorecard_checkxx
scorecard_statsx
scorecard_check_statsx
idp_scorexx
idp_workflowxexecute
idp_tech_docx

拉取請求

資源類型列表取得建立更新刪除執行操作
pull_requestxxxxclose、merge
pr_reviewerxxsubmit_review
pr_commentxxx
pr_checkx
pr_activityx

使用 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_processxxxxx
release_activityxxxxx
releasexx
release_execution_phasex
release_execution_taskx
release_execution_activityx
release_inputx
release_execution_phase_inputx
release_execution_phase_outputx
release_execution_activity_inputx
release_execution_activity_outputx

典型工作流程：

  1. harness_list(resource_type="release_process", org_id="...", project_id="...") 以探索編排流程定義。
  2. 在建立/更新之前先執行 harness_schema(resource_type="release_process")（或 release_activity）；接著使用 body.yaml 執行 harness_create / harness_update。
  3. harness_list(resource_type="release", org_id="...", project_id="...") 以尋找作用中或最近的版本（預設回溯 30 天；可選用 filters.status、filters.search_term、filters.days_back）。
  4. harness_get(resource_type="release", release_id="...") 以取得版本詳細資料。
  5. harness_list(resource_type="release_execution_phase", filters={ release_id: "..." }) 以取得階段狀態；release_execution_task 和 release_execution_activity 使用相同的 release_id。
  6. 對 release_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

預設啟用的 vibe 工具集涵蓋 ${HARNESS_BASE_URL}/vibe/v1 下的 Vibe Orchestrator BFF 合約。它使用現有的 Harness 連線和帳戶標頭，不會在請求主體中新增帳戶/組織/專案查詢參數或範圍欄位。團隊使用 Harness API 金鑰驗證（PAT/SAT）驗證了 Vibe 流程，因此預設工作階段不需要選擇加入設定。精選的 OpenAPI 文件說明 bearer/工作階段驗證；伺服器的 OAuth 模式會轉送目前工作階段的 bearer token。自動化回歸測試驗證兩種標頭路徑；閘道驗證仍受目標環境組態的約束。

資源類型列表取得建立更新刪除執行動作
vibe_projectxprepare、deploy
vibe_app_lifecyclexevents

API 支援兩種輸入路徑。請保留這些 API 原生請求格式：

提供給編碼代理的來源API 流程
GitHub 儲存庫連結/連接器harness_create 搭配 resource_type="vibe_project" 和 body.mode 以及模式特定欄位。合約命名了 github_link 和 github_connector，但未定義其 URL、分支或連接器欄位格式；這些欄位會轉發到後端，不會自行發明對應關係。
ZIP 檔案呼叫 prepare 並提供應用程式名稱和檔案中繼資料，將位元組上傳到傳回的簽署目標，然後呼叫 deploy。
本機來源目錄編碼代理會先將預期的工作區來源封裝成本機 ZIP，然後遵循 ZIP 流程。本機路徑或對話內容不是 API 支援的來源上傳方式。

封裝目錄時，請包含建置所需的來源、manifest、鎖定檔、組態和預期的未提交編輯。排除憑證、.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 為可選且可為 null。其他準備欄位會保留以供後端驗證，如 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_workspacex
fme_environmentxxxxx
fme_feature_flagxxxxxkill、restore、reallocate、archive、unarchive
fme_feature_flag_definitionxxxxxkill、restore、reallocate
fme_rollout_statusx
fme_rule_based_segmentxxxx
fme_rule_based_segment_definitionxxenable、disable、change_request
fme_traffic_typex
fme_identityxx
fme_standard_segmentxx
fme_segment_keysxx
fme_segmentxxxxx
fme_segment_definitionxxxxxlist_keys、add_keys、remove_keys
fme_metricxxxxx
fme_event_typexx

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 的 body：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 上的操作相同。Get/create/update body 符合舊版（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。建立 body：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）。在 fme_metric 的 baseEventTypes/filterEventType 或 event_type_ids 篩選中引用真實事件類型 ID 之前，請使用此資源來探索真實的事件類型 ID，而不是猜測 ID。

在單使用者/自架模式中，舊版模式驗證使用來自 HARNESS_FME_API_KEY 的 Bearer token，回退到非佔位符的 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_agentxx
gitops_argo_projectx
gitops_app_project_mappingxxxximport
gitops_autocreate_logx
gitops_applicationxxsync
gitops_clusterxx
gitops_repositoryxx
gitops_applicationsetxx
gitops_repo_credentialxx
gitops_app_eventx
gitops_pod_logx
gitops_managed_resourcex
gitops_resource_actionx
gitops_dashboardx
gitops_app_resource_treex
gitops_cluster_linkxxx

混沌工程

資源類型列表取得建立更新刪除執行動作
chaos_experimentxxxxrun, stop
chaos_experiment_runx
chaos_experiment_variablex
chaos_component_variablex
chaos_input_setxxxxx
chaos_experiment_templatexxxcreate_from_template, list_revisions, get_variables, get_yaml, compare_revisions
chaos_probexxxxenable, verify, get_manifest
chaos_probe_in_runx
chaos_probe_templatexxxget_variables
chaos_infrastructurex
chaos_k8s_infrastructurexxxcheck_health
chaos_enabled_infrastructurex
chaos_environmentx
chaos_hubxxxxx
chaos_hub_faultx
chaos_faultxxxget_variables, get_yaml
chaos_fault_templatexxxlist_revisions, get_variables, get_yaml, compare_revisions
chaos_fault_experiment_runx
chaos_actionxxxxget_manifest
chaos_action_templatexxxlist_revisions, get_variables, compare_revisions
chaos_loadtestxxxxxrun, stop
chaos_servicexxxxxlist_experiment_runs, list_load_tests
chaos_application_mapxx
discovered_agentx
discovered_namespacex
discovered_servicex
discovered_network_mapx
chaos_guard_conditionxxx
chaos_guard_rulexxxenable
chaos_recommendationxx
chaos_riskxx
chaos_dr_testxx
scanned_riskxxoccurrences, summary_by_service
chaos_risk_rulexx
chaos_risk_scanxxxxxretry, abort, report, report_download, heatmap

雲端成本管理 (CCM)

資源類型列表取得建立更新刪除執行動作
cost_perspectivexxxxx
cost_breakdownx
cost_timeseriesx
cost_summaryxx
cost_recommendationxxupdate_state, override_savings, create_jira_ticket, create_snow_ticket
cost_anomalyx
cost_anomaly_summaryx
cost_categoryxx
cost_account_overviewx
cost_filter_valuex
cost_recommendation_statsx
cost_recommendation_detailx
cost_commitmentx
ai_budgetxxxxx
ai_budget_overviewx
ai_budget_consumptionx
ai_budget_override_requestxxxapprove, reject

軟體工程洞察 (SEI)

SEI 資源已整合以提升 token 效率。使用 metric 或 aspect 參數取得 DORA、團隊/組織樹狀結構詳細資訊，以及 AI 洞察。

資源類型列表取得建立更新刪除執行動作
sei_metricx
sei_productivity_metricx
sei_dora_metricx傳入 metric：deployment_frequency、change_failure_rate、mttr、lead_time 或 *_drilldown
sei_teamxx
sei_team_detailx傳入 aspect：integrations、developers、integration_filters
sei_org_treexx
sei_org_tree_detailxx傳入 aspect：efficiency_profile、productivity_profile、business_alignment_profile、integrations、teams
sei_business_alignmentxx傳入 aspect：feature_metrics、feature_summary、drilldown 以取得資料
sei_ai_usagexx傳入 aspect：metrics、breakdown、summary、top_languages
sei_ai_adoptionxx傳入 aspect：metrics、breakdown、summary
sei_ai_impactx傳入 aspect：pr_velocity、rework
sei_ai_raw_metricx

軟體供應鏈安全 (SCS)

資源類型列表取得建立更新刪除執行動作
scs_artifact_sourcex
artifact_securityxx
scs_artifact_componentx
scs_artifact_remediationx
scs_chain_of_custodyx
scs_compliance_resultx
code_repo_securityxx
scs_sbomx

證據保管庫

證據保管庫儲存 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。

資源類型列表取得建立更新刪除執行動作
attestationxxdownload

安全測試編排（STO）

資源類型列表取得建立更新刪除執行動作
security_issuex
security_issue_filterx
security_exemptionxxapprove, reject
remediation_diffx

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。

存取控制

資源類型列表取得建立更新刪除執行動作
userxx
user_groupxxxxx
service_accountxxxx
rolexxxx
role_assignmentxx
resource_groupxxxx
permissionx

治理

資源類型列表取得建立更新刪除執行動作
policyxxxxx
policy_setxxxxx
policy_evaluationxx

部署凍結

資源類型列表取得建立更新刪除執行動作
freeze_windowxxxxxtoggle_status
global_freezexmanage

服務覆寫

資源類型列表取得建立更新刪除執行動作
service_overridexxxxx

設定

資源類型列表取得建立更新刪除執行動作
settingx

MCP 提示詞

DevOps

PromptDescriptionParameters
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、前置時間），附 Elite/High/Medium/Low 分級與改善建議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

PromptDescriptionParameters
optimize-costs分析雲端成本資料、呈現建議與異常，依潛在節省金額排序projectId (選填)
cloud-cost-breakdown依服務、環境或叢集深入分析雲端成本，附趨勢分析與異常偵測perspectiveId (選填), projectId (選填)
commitment-utilization-review分析預留執行個體與節省方案使用率，找出浪費並最佳化承諾projectId (選填)
cost-anomaly-investigation調查成本異常——判斷根本原因、受影響資源及修正措施projectId (選填)
rightsizing-recommendations檢視並排定權限調整建議的優先順序，可選擇建立 Jira 或 ServiceNow 工單projectId (選填), minSavings (選填)

DevSecOps

PromptDescriptionParameters
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審查拉取請求 — 分析 diff、提交、檢查和評論，以提供關於錯誤、安全性、效能和程式碼風格的結構化回饋repoId (必填), prNumber (必填), projectId (選填)
pr-summary從分支的提交歷史和 diff 自動產生 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:///pipelineHarness pipeline JSON Schemaapplication/schema+json
schema:///templateHarness template JSON Schemaapplication/schema+json
schema:///triggerHarness trigger JSON Schemaapplication/schema+json
schema:///pipeline_v1 (Alpha)Harness V1 pipeline JSON Schema（簡化 stages/steps 格式）application/schema+json
schema:///agent-pipelineHarness AI agent pipeline JSON Schemaapplication/schema+json
agent-docs:///legacy-format舊版 agent spec 格式參考（agent.step.group.steps / PLUGIN_TASK），由 create-agent prompt 在更新現有舊版格式 agent 時讀取text/markdown

工具集篩選

預設情況下，45 個工具集中的 41 個已啟用。四個工具集為選擇加入，並從預設中排除：

  • ansible — Harness Ansible（inventories、playbooks、hosts、activity）。選擇加入，因為它屬於專案範圍，並增加了許多使用者不需要的概念。
  • autonomous_work — Development Harness（自主工作）。選擇加入；請參閱工具集描述以了解範圍。
  • observability-evaluations — 排定的生產遙測評估規則。選擇加入，因為它依賴於已部署的評分控制平面。
  • registries-v3 — Harness Artifact Registry v3（packages、versions、files、metadata、scans、firewall exceptions）。選擇加入，直到 v3 寫入功能落地，因此 agent 不必在 v1 registries/artifacts 和 v3 packages/versions 之間進行區分。

使用 + 前綴新增工具集

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

# Explicitly include Ansible alongside all defaults
HARNESS_TOOLSETS=+ansible

移除預設工具集

使用 - 前綴來排除您不需要的工具集：

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

結合 + 和 -

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

明確允許清單

明確的逗號分隔清單（無前綴）會完全取代預設值。僅啟用列出的工具集：

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

可用的工具集名稱：

工具集資源類型
platformorganization, project
pipelinespipeline, pipeline_v1, pipeline_dynamic_execution, execution, execution_inputs, trigger, pipeline_summary, input_set, approval_instance
agentsagent, agent_run
servicesservice
environmentsenvironment
connectorsconnector, connector_catalogue
infrastructureinfrastructure
secretssecret
logsexecution_log
auditaudit_event
delegatesdelegate, delegate_token
repositoriesrepository, branch, commit, file_content, tag, repo_rule, space_rule
registriesregistry, artifact, artifact_version, artifact_file
file_storefile_store
templatestemplate
dashboardsdashboard, dashboard_data
idpidp_entity, scorecard, scorecard_check, scorecard_stats, scorecard_check_stats, idp_score, idp_workflow, idp_tech_doc
pull-requestspull_request, pr_reviewer, pr_comment, pr_check, pr_activity
feature-flagsfme_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
gitopsgitops_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
chaoschaos_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
ccmcost_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
seisei_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
scsscs_artifact_source, artifact_security, scs_artifact_component, scs_artifact_remediation, scs_chain_of_custody, scs_compliance_result, code_repo_security, scs_sbom
evidence-vaultattestation
stosecurity_issue, security_issue_filter, security_exemption, remediation_diff
dbopsdatabase_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_controluser, user_group, service_account, role, role_assignment, resource_group, permission
governancepolicy, policy_set, policy_evaluation
freezefreeze_window, global_freeze
overridesservice_override
settingssetting
knowledge-graphkg_queryable_type_summary, kg_grammar, hql_query
semantic-layerkg_type, kg_related_type
ai-evalseval_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
iacmiacm_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-managementrelease_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
vibevibe_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 |
                 +-------------------+

運作方式

  1. 工具是通用動詞：harness_list、harness_get 等。它們接受一個 resource_type 參數，用於路由到正確的 API 端點。
  2. 註冊表將每個 resource_type 映射到一個 ResourceDefinition——一個宣告式資料結構，指定 HTTP 方法、URL 路徑、路徑/查詢參數映射，以及回應提取邏輯。
  3. 分派解析資源定義、建構 HTTP 請求（路徑替換、查詢參數、resource_scope 感知的帳戶/組織/專案注入）、透過 HarnessClient 呼叫 Harness API，並提取相關的回應資料。
  4. 工具集過濾（HARNESS_TOOLSETS）控制在啟動時將哪些資源定義載入註冊表。
  5. 結構化輸出使用 MCP outputSchema 宣告；harness_list 將陣列和常見的列表包裝器強制轉換為物件形狀的 structuredContent，以支援嚴格的用戶端。
  6. 深層連結會自動附加到回應中，為每個資源提供直接的 Harness UI URL。
  7. 精簡模式會從列表結果中移除冗長的中繼資料，僅保留可操作的欄位（身分、狀態、類型、時間戳記、深層連結），以最小化 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）會靜默執行，不顯示提示。當顯示提示時，使用者會看到即將執行的操作並選擇接受或拒絕，為實際變更或執行事物的操作提供真正的人員介入核准。

運作方式：

  1. LLM 以 medium_write+ 風險呼叫寫入工具（例如 harness_delete、harness_execute pipeline.run）。低風險的建立/更新/讀取不會顯示提示。
  2. 伺服器向用戶端發送引導確認請求，包含操作摘要和一個 confirm 核取方塊（預設勾選）。
  3. 使用者檢視詳細資訊並點擊接受（勾選 confirm）或拒絕/取消。
  4. 如果以勾選 confirm: true 的方式接受，操作會繼續執行。如果以未勾選 confirm 的方式接受、拒絕或取消，操作會被封鎖並告知 LLM（明確拒絕是權威性的，不會被工具呼叫上的 confirm: true 繞過）。

用戶端支援：

用戶端引導確認支援
Cursor是
VS Code (Copilot)是
Claude Desktop尚未支援
Devin Desktop尚未支援
MCP Inspector是

當用戶端缺少支援時，引導確認行為會因操作風險而異：

風險等級用戶端支援引導確認傳遞 confirm: true行為
read、low_write任何任何靜默執行——不顯示提示（confirm 在此風險等級無效）
medium_write、high_write、destructive是任何提示使用者。僅在使用者勾選 confirm: true（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。當用戶端無法顯示提示或回傳退化的接受（{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 搭配良好——這是一組現成的 Claude Code 技能（斜線指令），專為常見的 Harness 工作流程設計。將它們與此 MCP 伺服器一起安裝，即可獲得如 /deploy、/rollback、/triage 等的高階自動化，而無需編寫自訂提示詞。

疑難排解與常見陷阱

症狀可能原因處理方式
HARNESS_ACCOUNT_ID is required when the API key does not include an account ID segment...API 金鑰不是受支援的帳戶範圍格式（pat.<accountId>... 或 sat.<accountId>...），因此無法推斷帳戶 ID明確設定 HARNESS_ACCOUNT_ID
啟動時出現 Unknown transport: "..."不支援的 CLI 傳輸參數僅使用 stdio 或 http
啟動時出現 Invalid HARNESS_TOOLSETS: ...一個或多個工具集名稱無法辨識僅使用 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 以建立新工作階段，然後使用新標頭重試
在 /mcp 上出現 HTTP 405 Method Not AllowedMCP 端點不支援的方法僅使用 POST、GET、DELETE 或 OPTIONS
HTTP Invalid requestJSON 內文無效或請求內文超過 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 allowedHARNESS_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 下載回傳 403Harness 託管的日誌 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 HTTPSHARNESS_BASE_URL 設定為 HTTP URL使用 HTTPS，或為本機開發設定 HARNESS_ALLOW_HTTP=true

授權

MIT