Harness

공식

Harness 플랫폼 데이터(파이프라인, 리포지토리, 로그, 아티팩트 레지스트리 포함)에 접근하고 상호작용합니다.

GitHub

114

Harness MCP(으)로 무엇을 할 수 있나요?

Harness 리소스 탐색 — harness_list를 통해 에이전트에게 파이프라인, 서비스, 환경, 조직, 프로젝트 또는 기능 플래그 목록을 요청하세요.
특정 리소스 검사 — harness_get을 사용해 지원되는 274가지 Harness 리소스 유형의 세부 정보를 가져오세요.
Harness 객체 생성 — harness_create를 통해 에이전트가 파이프라인이나 프로젝트 같은 리소스를 생성하도록 하세요.
프로젝트 전반에서 작업 — "모든 프로젝트에서 실패한 실행을 보여줘"라고 요청하면 에이전트가 계정 계층 구조를 동적으로 탐색합니다.
사전 구축된 워크플로 프롬프트 사용 — 35개의 프롬프트 템플릿으로 실패한 파이프라인 디버깅, DORA 지표 검토, 취약점 분류 및 클라우드 비용 최적화를 수행할 수 있습니다.

문서

Harness MCP Server 2.0

AI 에이전트가 11개의 통합 도구와 274개의 리소스 유형을 통해 Harness.io 플랫폼에 완전히 액세스할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.

이 MCP 서버를 사용하는 이유

대부분의 MCP 서버는 API 엔드포인트마다 도구 하나를 매핑합니다. Harness처럼 범위가 넓은 플랫폼에서는 도구가 240개 이상 필요하며, 도구 수가 늘어날수록 LLM의 도구 선택 성능은 저하됩니다. 컨텍스트 창은 스키마로 가득 차고, 엔드포인트가 추가될 때마다 새 코드가 필요합니다.

이 서버는 다른 방식으로 설계되었습니다.

도구 11개, 리소스 유형 274개. 레지스트리 기반 디스패치 시스템이 harness_list, harness_get, harness_create 등을 모든 Harness 리소스(파이프라인, 서비스, 환경, 조직, 프로젝트, 기능 플래그, 비용 데이터 등)로 라우팅합니다. LLM은 수백 개가 아닌 11개 도구 중에서 선택합니다.
플랫폼 전체를 지원합니다. CI/CD, GitOps, 기능 플래그, 클라우드 비용 관리, 보안 테스트, 카오스 엔지니어링, 데이터베이스 DevOps, 내부 개발자 포털, 소프트웨어 공급망, 코드형 인프라 관리, 릴리스 관리, 거버넌스, 서비스 재정의, 지식 그래프 등을 아우르는 기본 도구 세트 44개를 제공합니다. 필요에 따라 Ansible 및 관측성 평가 지원을 선택적으로 사용할 수 있습니다.
여러 프로젝트를 대상으로 하는 워크플로를 기본 제공됩니다. 에이전트는 조직과 프로젝트를 동적으로 검색하므로 하드코딩된 환경 변수가 필요하지 않습니다. "모든 프로젝트에서 실패한 실행을 보여 줘"라고 요청하면 에이전트가 전체 계정 계층을 탐색할 수 있습니다.
프롬프트 템플릿 35개. 앱의 빌드 및 배포 전체 과정, 실패한 파이프라인 디버깅, DORA 메트릭 검토, 취약점 분류, 클라우드 비용 최적화, 액세스 제어 감사, 기능 플래그 롤아웃 계획, 풀 리퀘스트 검토, 대기 중인 파이프라인 승인 등 일반적인 워크플로를 위한 사전 제작 프롬프트를 제공합니다.
어디서나 작동합니다. 로컬 클라이언트(Claude Desktop, Cursor, Devin Desktop)용 Stdio 전송, 원격/공유 배포용 HTTP 전송을 지원하며 Docker 및 Kubernetes를 사용할 수 있습니다.
구성 없이 바로 시작할 수 있습니다. Harness API 키만 제공하면 됩니다. 계정 ID는 PAT 및 SAT 토큰에서 자동으로 추출되며, 조직/프로젝트 기본값은 선택 사항이고, 도구 세트 필터링으로 필요한 항목만 노출할 수 있습니다.
확장성을 고려해 설계되었습니다. 새 Harness 리소스를 추가하려면 선언형 데이터 파일만 추가하면 됩니다. 새 도구 등록, 스키마 변경, 프롬프트 업데이트는 필요하지 않습니다.

사전 요구 사항

서버를 설치하거나 실행하기 전에 Harness API 키가 필요합니다.

Harness 계정에 로그인합니다.
My Profile → API Keys → + New API Key로 이동합니다.
API 키 아래에 새 Token을 만듭니다. 그러면 <prefix>.<accountId>.<tokenId>.<secret> 형식의 PAT 또는 SAT가 생성됩니다.
토큰을 안전한 곳에 저장합니다. 다음 단계에서 필요합니다.

자세한 안내는 Harness API 빠른 시작을 참조하세요.

빠른 시작

옵션 0: 호스팅 Harness MCP

Harness 계정에서 호스팅 MCP 서비스가 활성화되어 있으면 원격 MCP 서버를 지원하는 클라이언트는 서버를 로컬에서 실행하는 대신 관리형 엔드포인트에 직접 연결할 수 있습니다.

중요: 호스팅 MCP 서비스는 HARNESS_API_KEY이 아닌 Harness Platform OAuth를 사용합니다. 엔드포인트를 사용하려면 먼저 계정별로 Harness Support에서 활성화하고 구성해야 합니다.

구성 예시는 호스팅 Harness MCP를 참조하세요.

옵션 1: npx(권장)

설치할 필요 없이 바로 실행하면 됩니다.

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

또는 AI 클라이언트에서 API 키를 구성하세요(아래 클라이언트 구성 참조).

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

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

참고: 계정 ID는 PAT 및 SAT 토큰(pat.<accountId>... 또는 sat.<accountId>...)에서 자동으로 추출되므로, 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 Directory 번들

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 모드에서 실행하면 서버는 다음을 노출합니다.

엔드포인트	메서드	설명
`/mcp`	`POST`	MCP JSON-RPC 엔드포인트(initialize 및 세션 요청)
`/mcp`	`GET`	서버가 시작한 메시지(진행 상황, 사용자 입력 요청)를 위한 SSE 스트림
`/mcp`	`DELETE`	활성 MCP 세션 종료
`/mcp`	`OPTIONS`	CORS 사전 요청
`/health`	`GET`	상태 확인 — `{ "status": "ok", "sessions": <count> }` 반환
`/.well-known/oauth-protected-resource`	`GET`	`oauth` 및 `oauth-proxy` 모드의 RFC 9728 메타데이터
`/.well-known/oauth-protected-resource/mcp`	`GET`	기본 `/mcp` 리소스의 경로 인식 RFC 9728 메타데이터
`/.well-known/oauth-authorization-server`	`GET`	`oauth-proxy` 모드의 임베디드 브로커 RFC 8414 메타데이터
`/oauth/authorize`	`GET`	업스트림 공급자 및 HarnessID를 통한 MCP 클라이언트 로그인 시작
`/oauth/upstream/callback`	`GET`	업스트림 ID 공급자 콜백
`/oauth/harnessid/callback`	`GET`	HarnessID 로그인 콜백
`/oauth/token`	`POST`	MCP 클라이언트용 업스트림 토큰 반환 또는 갱신. HarnessID 토큰은 반환하지 않음

HTTP 전송은 세션 기반 모드로 실행됩니다. initialize에서 새 MCP 세션이 생성되고 서버가 mcp-session-id 헤더를 반환합니다. 이후 해당 세션에 대한 요청에는 동일한 헤더를 포함해야 합니다.

HTTP 모드의 운영상 제약 사항:

공유 배포 또는 원격에서 접근 가능한 단일 사용자 및 다중 사용자 배포에는 HARNESS_MCP_AUTH_TOKEN을 설정하세요. 설정하면 /mcp에 대한 모든 POST, GET, DELETE 요청에 Authorization: Bearer <token>을 포함해야 합니다.
OAuth 모드는 HARNESS_MCP_AUTH_TOKEN 대신 HarnessID 액세스 토큰을 허용하며, 인증되지 않은 액세스를 허용하는 설정 없이도 루프백이 아닌 주소에 바인딩할 수 있습니다.
OAuth 프록시 모드는 업스트림 ID 공급자 토큰을 허용하고, 이를 내부적으로 사용자별 HarnessID 토큰으로 교환하며, 모든 요청에 업스트림 토큰을 요구합니다.
기본적으로 루프백이 아닌 주소에 바인딩하는 단일 사용자 및 다중 사용자 배포에는 HARNESS_MCP_AUTH_TOKEN가 필요합니다. 루프백이 아닌 인터페이스에서 인증 없이 실행하려면 HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP=true을 명시적으로 설정하세요.
mcp-session-id가 없는 POST /mcp는 initialize 요청이어야 합니다.
기존 세션에 대한 POST /mcp, GET /mcp, DELETE /mcp에는 mcp-session-id 헤더가 필요합니다.
GET /mcp은 SSE 알림(진행 상황 업데이트 및 사용자 입력 요청)에 사용됩니다.
요청이나 SSE 스트림이 활성화되어 있지 않으면 유휴 세션은 MCP_SESSION_TTL_MS밀리초 후 정리됩니다(기본값은 1800000, 즉 30분).
GET /health은 유일한 비-MCP 엔드포인트입니다.
요청 본문 크기는 HARNESS_MAX_BODY_SIZE_MB로 제한됩니다(기본값은 10MB).
initialize 요청에 x-harness-pipeline-version: 0 또는 1을 설정하여 해당 HTTP 세션의 V0 또는 V1 파이프라인 리소스를 선택하세요.
initialize 요청에 x-harness-auto-approve-risk: none|low_write|medium_write|high_write|all을 설정하여 세션별 자동 승인 임계값을 더 엄격하게 지정하세요. 서버는 이 값을 배포 수준의 HARNESS_AUTO_APPROVE_RISK 이하로 제한하므로 세션에서 구성된 승인 한도를 낮출 수는 있지만 높일 수는 없습니다.

HarnessID OAuth 모드

원격 MCP 클라이언트가 HarnessID를 검색하고 PKCE를 사용하는 OAuth 2.1 Authorization Code 흐름을 완료하도록 하려면 HARNESS_MCP_MODE=oauth을 설정하세요. OAuth 모드는 HTTP 전송에서만 사용할 수 있습니다. 프로덕션 HarnessID, MCP 리소스 및 API 라우팅 기본값이 내장되어 있습니다.

HARNESS_MCP_MODE=oauth

기본값은 발급자 https://id.harness.io/idp/realms/HarnessIDP, 리소스 https://mcp.harness.io/mcp, OAuth 클라이언트 mcp-client, Harness API 기본 URL https://mcp.harness.io/cli입니다. QA, 로컬 개발 또는 다른 Harness 환경에서만 재정의하세요.

이 모드에서는 HARNESS_API_KEY을 설정하면 안 됩니다. HARNESS_MCP_OAUTH_JWKS_URI의 기본값은 <issuer>/protocol/openid-connect/certs이며, 계정은 토큰에서 가져오므로 HARNESS_ACCOUNT_ID은 필요하지 않습니다. 선택적 appsec 도구 세트(HARNESS_TOOLSETS=+appsec)가 활성화된 경우 세션은 initialize 요청에 x-harness-appsec-api-key도 전달해야 합니다(HarnessID OAuth 토큰은 api.traceable.ai으로 전달되지 않습니다).

서버는 RFC 9728 보호 리소스 메타데이터를 게시하고 클라이언트가 인증되지 않은 경우 다음 챌린지를 반환합니다.

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

서버는 구성된 JWKS 엔드포인트를 사용해 HarnessID 액세스 토큰의 RS256 서명, iss, 만료 시간 및 sub을 검증하고, azp 클레임을 통해 토큰이 HARNESS_MCP_OAUTH_CLIENT_ID에 발급되었는지 확인합니다. HARNESS_MCP_OAUTH_RESOURCE은 검색 및 챌린지에 사용되는 RFC 9728 보호 리소스 식별자입니다. 현재 HarnessID 액세스 토큰은 MCP URL 대신 aud: account를 사용하므로 리소스는 aud과 비교되지 않습니다.

계정 ID는 토큰의 HARNESS_MCP_OAUTH_ACCOUNT_CLAIM 클레임에서 가져옵니다(기본값은 account_id). 이 클레임은 HarnessID organization 범위에서 채워집니다. 각 세션은 호출자의 액세스 토큰을 저장하고 이를 Authorization: Bearer로 Harness API에 전달하므로 Harness RBAC 및 감사 기록에는 공유 PAT가 아닌 로그인한 사용자가 반영됩니다. 세션은 생성 시 사용한 sub 및 계정에 바인딩됩니다. 이후 요청에 갱신된 토큰을 사용할 수 있지만, 다른 사용자 또는 계정의 토큰은 거부됩니다.

일반적으로 클라이언트에는 MCP 리소스 URL만 필요합니다.

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

클라이언트는 보호 리소스 메타데이터를 읽고 HARNESS_MCP_OAUTH_ISSUER를 검색한 다음 해당 인증 서버의 RFC 8414 메타데이터를 사용합니다. 클라이언트가 동적 클라이언트 등록을 지원하지 않으면 사전 등록된 mcp-client 클라이언트 ID를 사용하세요.

QA Keycloak 체크리스트와 검증 명령은 자체 호스팅 MCP 서버용 HarnessID OAuth를 참조하세요.

업스트림 ID 공급자 OAuth 프록시 모드

OAuth 프록시 모드에는 기밀 HarnessID 클라이언트가 필요합니다. Harness ID 팀에서 해당 클라이언트를 만들고 클라이언트 ID와 클라이언트 시크릿을 제공합니다. 이 모드를 활성화하기 전에 Harness ID 팀에 문의하세요.

MCP 클라이언트가 업스트림 ID 공급자 토큰만 보유해야 하는 경우 HARNESS_MCP_MODE=oauth-proxy을 설정하세요. 공개 클라이언트 이름은 무엇이든 사용할 수 있습니다. HARNESS_MCP_BROKER_CLIENT_ID를 MCP 클라이언트에서 사용하는 이름과 동일하게 설정하세요. 통합 OAuth 브로커는 업스트림 브라우저 로그인을 시작하고 동일한 흐름에서 HarnessID 로그인을 완료한 다음, 업스트림 액세스 토큰과 갱신 토큰만 MCP 클라이언트에 반환합니다. 모든 /mcp 요청에서 서버는 업스트림 토큰을 검증하고 캐시된 사용자별 HarnessID 액세스 토큰을 사용하며, 만료 전에 갱신 토큰으로 이를 갱신합니다. 업스트림 토큰과 HarnessID 토큰 간 매핑이 없으면 401을 반환하여 클라이언트가 다시 로그인하도록 합니다. HarnessID 토큰은 서버에만 보관됩니다. 갱신 토큰, 캐시된 액세스 토큰 및 임시 OAuth 상태는 저장 시 암호화됩니다. 이 모드는 HTTP 전용입니다. 또한 업스트림 발급자와 대상, 안정적인 32바이트 볼트 키가 필요합니다. 구성 및 엔드투엔드 MCP 테스트 명령은 업스트림 ID 공급자 OAuth 프록시 모드를 참조하세요.

다중 사용자 모드

각 클라이언트가 서로 다른 Harness 사용자로 인증하는 공유 HTTP 배포에서는 HARNESS_MCP_MODE=multi-user을 설정하세요. 이 모드에서는 다음과 같습니다.

서버 구성에서 HARNESS_API_KEY을 설정하면 안 됩니다. 서버에는 Harness 자격 증명이 없습니다.
각 세션은 initialize 요청에 x-harness-api-key을 제공해야 합니다. API 키에 계정 세그먼트가 포함되지 않은 경우에만 x-harness-account-id이 필요합니다.
세션은 해당 세션의 기본 범위를 설정하기 위해 x-harness-org 및 x-harness-project 헤더도 제공할 수 있습니다.
옵트인 appsec 도구 세트(HARNESS_TOOLSETS=+appsec)가 활성화된 경우, appsec_* 리소스를 호출하는 세션은 initialize 요청에 x-harness-appsec-api-key도 제공해야 합니다(세션의 x-harness-api-key은 api.traceable.ai으로 전달되지 않습니다).
Harness API 키는 해당 세션의 모든 Harness API 호출에 전달되므로 Harness의 감사 추적에 실제 사용자가 반영됩니다.
HARNESS_MCP_AUTH_TOKEN은 독립적이며 추가 전송 계층 게이트로 계속 사용할 수 있습니다.

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

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

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

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

HARNESS_MCP_ALLOWED_HOSTS은 DNS 리바인딩 방지를 위한 Host 헤더 검증을 제어하고, CORS는 브라우저 출처를 제한합니다. 둘 다 인증 기능이 아닙니다. 액세스 제어에는 HARNESS_MCP_AUTH_TOKEN 또는 인증된 게이트웨이/리버스 프록시를 사용하세요.

클라이언트 구성

참고: HARNESS_ORG 및 HARNESS_PROJECT는 선택 사항입니다. 도구 호출별로 지정하지 않았을 때 사용할 조직 ID와 프로젝트 ID를 설정합니다. 에이전트는 harness_list(resource_type="organization") 및 harness_list(resource_type="project")를 사용해 조직과 프로젝트를 동적으로 검색할 수 있습니다. 더 이상 사용되지 않는 이름인 HARNESS_DEFAULT_ORG_ID 및 HARNESS_DEFAULT_PROJECT_ID도 이전 버전과의 호환성을 위해 계속 허용됩니다.

호스팅 Harness MCP

Harness는 관리형 서비스가 활성화된 계정에 호스팅 MCP 엔드포인트도 제공합니다. npx harness-mcp-v2을 실행하거나 HTTP 전송을 직접 셀프 호스팅하는 대신 공유 원격 MCP 엔드포인트를 사용하려는 경우 유용합니다.

중요: 호스팅 MCP 인증에는 Harness Platform OAuth가 사용됩니다. 클라이언트 구성에서 HARNESS_API_KEY을 사용하지 않습니다. 호스팅 MCP 사용 가능 여부는 Harness 계정별로 구성되므로, 사용하기 전에 Harness Support에 문의해 설정을 활성화하고 구성해야 합니다.

호스팅 엔드포인트 https://mcp.harness.io/mcp은 관리형 서비스입니다. Claude, Cursor 또는 Cowork의 클라이언트 측 MCP 구성으로는 요청이 라우팅되는 Harness 환경을 재정의할 수 없습니다. Harness0 또는 다른 비공개 Harness SaaS 환경에서 사용하려면 Harness Support에 문의해 해당 환경의 호스팅 MCP를 활성화하고 구성하거나, 로컬/셀프 호스팅 서버를 실행하고 HARNESS_BASE_URL을 대상 Harness 호스트로 설정하세요.

호스팅 MCP 예시:

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

호스팅 항목과 로컬 항목을 함께 사용하는 예시:

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

npx ENOENT 또는 node: No such file or directory 문제 해결

이는 클라이언트 프로세스 실행 실패이며 Harness 인증 실패가 아닙니다. MCP 서버가 아직 시작되지 않았으므로 HARNESS_API_KEY을 변경해도 spawn npx ENOENT에는 영향을 주지 않습니다.

GUI 앱(Cursor, Claude Desktop, Devin Desktop, VS Code)은 셸의 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 (via `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개의 MCP 서버에 연결하는 대신 단일 엔드포인트 사용
액세스 제어 — 팀별로 사용할 수 있는 도구 제한

Docker MCP Gateway

Docker MCP Gateway 구성에 서버를 등록하세요.

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

Portkey

엔터프라이즈 거버넌스, 비용 추적 및 다중 LLM 라우팅을 위해 Harness MCP 서버를 Portkey MCP Gateway에 추가하세요.

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

LiteLLM

LiteLLM 프록시 구성에 추가하세요.

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

Envoy AI Gateway

서버는 HTTP 전송을 통해 Envoy AI Gateway의 MCP 지원과 함께 작동합니다.

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

그런 다음 Envoy가 http://localhost:8080/mcp을 업스트림 MCP 백엔드로 라우팅하도록 구성하세요.

Kong

Kong의 AI MCP Proxy 플러그인을 사용해 기존 Kong 게이트웨이 인프라를 통해 Harness MCP 서버를 노출하세요.

기타 게이트웨이

MCP 사양을 지원하는 모든 게이트웨이(Microsoft MCP Gateway, IBM ContextForge, Cloudflare Workers 등)는 이 서버를 프록시할 수 있습니다. stdio 기반 게이트웨이에는 기본 전송을 사용하세요. HTTP 기반 게이트웨이에는 서버를 http 전송으로 시작하고 게이트웨이가 /mcp 엔드포인트를 가리키도록 설정하세요.

Docker

서버를 Docker 컨테이너로 빌드하고 실행하세요.

# Build the image
pnpm docker:build

# Run with your .env file
pnpm docker:run

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

컨테이너는 기본적으로 포트 3000에서 HTTP 모드로 실행되며 기본 제공 상태 확인 기능을 포함합니다.

Kubernetes

제공된 매니페스트를 사용해 Kubernetes 클러스터에 배포하세요.

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

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

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

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

배포는 준비 상태/활성 상태 프로브, 리소스 제한 및 비루트 보안 컨텍스트를 갖춘 복제본 2개를 실행합니다. Service는 내부적으로 포트 80을 노출하며 컨테이너 포트 3000을 대상으로 합니다.

구성

서버는 프로젝트 루트에 .env 파일이 있으면 해당 파일에서 환경 변수를 자동으로 불러옵니다. .env.example을 .env에 복사하고 값을 입력하세요. 환경 변수는 셸이나 MCP 클라이언트 구성에서도 설정할 수 있습니다.

변수	필수	기본값	설명
`HARNESS_MCP_MODE`	아니요	`single-user`	배포 모드: `single-user`, `multi-user`, `oauth`(직접 HarnessID 토큰) 또는 `oauth-proxy`(사용자별 HarnessID 토큰으로 교환되는 업스트림 ID 공급자 토큰)
`HARNESS_API_KEY`	예*	--	Harness 개인 액세스 토큰 또는 서비스 계정 토큰. `single-user` 모드에서 필수입니다. 각 세션이 자체 자격 증명을 제공하는 `multi-user`, `oauth` 또는 `oauth-proxy` 모드에서는 설정하면 안 됩니다.
`HARNESS_ACCOUNT_ID`	아니요	(PAT/SAT에서 가져옴)	Harness 계정 식별자. 단일 사용자 모드에서는 PAT/SAT 토큰에서 자동으로 추출됩니다. API 키에 계정 식별자가 포함되지 않은 경우 다중 사용자 세션은 `x-harness-account-id`를 통해 자체 식별자를 제공할 수 있습니다.
`HARNESS_BASE_URL`	아니요	`https://app.harness.io`(`oauth` 및 `oauth-proxy`에서는 `https://mcp.harness.io/cli`)	Harness API/UI 기본 URL. `oauth` 및 `oauth-proxy`는 기본적으로 호스팅된 MCP `/cli` 프록시를 통해 라우팅됩니다. 다른 모드는 Harness SaaS API를 직접 사용합니다.
`HARNESS_MCP_OAUTH_ISSUER`	아니요	`https://id.harness.io/idp/realms/HarnessIDP`	액세스 토큰의 `iss` 클레임과 정확히 일치하는 HarnessID 발급자
`HARNESS_MCP_OAUTH_RESOURCE`	아니요	`https://mcp.harness.io/mcp`	RFC 9728 리소스 식별자로 게시되는 공개 표준 MCP URL
`HARNESS_MCP_OAUTH_JWKS_URI`	아니요	`<issuer>/protocol/openid-connect/certs`	RS256 액세스 토큰 서명을 검증하는 데 사용되는 HarnessID JWKS 엔드포인트
`HARNESS_MCP_OAUTH_CLIENT_ID`	아니요	`mcp-client`	액세스 토큰이 발급되어야 하는 HarnessID 클라이언트. 토큰의 `azp` 클레임과 대조하여 확인합니다.
`HARNESS_MCP_OAUTH_ACCOUNT_CLAIM`	아니요	`account_id`	Harness 계정 ID를 포함하는 액세스 토큰 클레임. HarnessID `organization` 범위에 의해 채워집니다.
`HARNESS_MCP_OAUTH_SCOPES`	아니요	`openid profile email organization`	RFC 9728 보호 리소스 메타데이터에 광고되는 공백으로 구분된 범위
`HARNESS_MCP_OAUTH_CLIENT_SECRET`	예*	--	Harness ID 팀에서 발급한 기밀 HarnessID 클라이언트 시크릿. `oauth-proxy` 모드에서만 필요합니다.
`HARNESS_MCP_OAUTH_EXTERNAL_SUB_CLAIM`	아니요	`external_sub`	연결 과정에서 업스트림 주체 또는 업스트림 이메일과 대조하는 HarnessID 토큰 클레임
`HARNESS_MCP_OAUTH_PROXY_GRANT`	아니요	`refresh`	`oauth-proxy` 모드의 후속 요청 권한 부여: `refresh` 또는 `jwt-bearer`
`HARNESS_MCP_OAUTH_PROXY_PUBLIC_URL`	예*	--	OAuth 브로커의 공개 출처. `oauth-proxy` 모드에서 필수이며 `HARNESS_MCP_OAUTH_RESOURCE`와 출처가 같아야 합니다.
`HARNESS_MCP_OAUTH_PROXY_VAULT_MODE`	아니요	`file`	`file`은 단일 파드의 로컬 디스크에 암호화된 볼트를 저장합니다. `redis`은 파드 간에 새로 고침 토큰과 로그인 상태를 공유합니다.
`HARNESS_MCP_OAUTH_PROXY_VAULT_PATH`	아니요	`.harness-mcp/oauth-proxy-vault.enc`	볼트 모드가 `file`일 때 사용되는 암호화된 HarnessID 토큰 및 로그인 상태 파일
`HARNESS_MCP_OAUTH_PROXY_VAULT_KEY`	예*	--	`oauth-proxy` 모드에 필요한 Base64 인코딩 32바이트 AES 키
`HARNESS_MCP_OAUTH_PROXY_REDIS_URL`	예*	--	볼트 모드가 `redis`일 때 필요한 `rediss://` URL. `redis://`에는 `HARNESS_ALLOW_HTTP=true`이 필요합니다. Redis 6.2 이상
`HARNESS_MCP_OAUTH_PROXY_REDIS_KEY_PREFIX`	아니요	`harness-mcp:oauth`	Redis의 OAuth 볼트 키 접두사
`HARNESS_MCP_UPSTREAM_ISSUER`	예*	--	`oauth-proxy` 모드에 필요한 정확한 업스트림 토큰 발급자
`HARNESS_MCP_UPSTREAM_AUDIENCE`	예*	--	`oauth-proxy` 모드에 필요한 정확한 업스트림 토큰 대상
`HARNESS_MCP_UPSTREAM_JWKS_URI`	아니요	`<upstream issuer>/v1/keys`	업스트림 RS256 JWKS 엔드포인트
`HARNESS_MCP_UPSTREAM_SCOPES`	아니요	`openid profile email offline_access`	내장 브로커가 요청하고 MCP 클라이언트에 게시하는 범위
`HARNESS_MCP_UPSTREAM_OAUTH_CLIENT_ID`	예*	--	내장 브로커에서 사용하는 기밀 업스트림 OAuth 클라이언트
`HARNESS_MCP_UPSTREAM_OAUTH_CLIENT_SECRET`	예*	--	서버에서만 사용하는 업스트림 OAuth 클라이언트 시크릿
`HARNESS_MCP_UPSTREAM_DISCOVERY_URI`	아니요	`<upstream issuer>/.well-known/openid-configuration`	업스트림 OIDC 검색 엔드포인트
`HARNESS_MCP_UPSTREAM_EMAIL_DOMAINS`	아니요	--	쉼표로 구분된 도메인. 이메일 연결에는 `email_verified=true` 및 이 목록에 있는 도메인이 필요합니다. 목록이 비어 있으면 이메일로 연결하지 않습니다.
`HARNESS_MCP_BROKER_ISSUER`	아니요	OAuth 프록시 공개 URL	MCP 클라이언트가 검색하는 인증 서버 발급자
`HARNESS_MCP_BROKER_CLIENT_ID`	아니요	`cursor-harness-mcp`	공개 OAuth 클라이언트 ID. MCP 클라이언트가 같은 값으로 구성되어 있다면 어떤 이름이든 사용할 수 있습니다.
`HARNESS_MCP_BROKER_REDIRECT_URIS`	아니요	(비어 있음)	쉼표로 구분된 리디렉션 URI. 비어 있으면 모든 콜백이 거부됩니다. `*`는 루프백 `http`/`https`만 허용합니다. 사용자 지정 스킴은 정확히 일치하도록 나열해야 합니다.
`HARNESS_MCP_BROKER_CODE_TTL_MS`	아니요	`60000`	MCP 클라이언트에 발급되는 일회용 인증 코드의 유효 기간
`HARNESS_MCP_BROKER_TRANSACTION_TTL_MS`	아니요	`600000`	연결된 브라우저 인증 트랜잭션의 최대 유효 기간
`HARNESS_FME_API_KEY`	아니요	--	레거시(`workspace_id`) 모드에서만 `fme_` 리소스에 사용하는 선택적 단일 사용자/자체 호스팅 FME/Split Admin 자격 증명. OAuth 모드에서는 레거시 FME를 사용할 수 없으므로 HarnessID 토큰은 `api.split.io`로 전송되지 않습니다. 대신 Harness 네이티브 `org_id`+`project_id` 범위를 사용하세요. `multi-user`, `oauth` 또는 `oauth-proxy` 모드에서는 설정하면 안 됩니다.
`HARNESS_FME_BASE_URL`	아니요	`https://api.split.io`	레거시(`workspace_id`) 모드에서만 `fme_` 리소스에 사용하는 Split/FME Admin API 기본 URL. 로컬 개발에서 HTTP URL을 사용하려면 `HARNESS_ALLOW_HTTP=true`가 필요합니다. Harness 네이티브(`org_id`+`project_id`) 모드에서는 이 값을 무시하고 대신 표준 `HARNESS_API_KEY`/`HARNESS_BASE_URL`을 사용합니다.
`HARNESS_APPSEC_API_KEY`	아니요	--	`appsec_` 리소스(`HARNESS_TOOLSETS=+appsec`)에 사용하는 선택적 단일 사용자 Traceable Platform API 토큰. `HARNESS_API_KEY`, 세션 `x-harness-api-key` 및 HarnessID OAuth 토큰은 Traceable로 전달되지 않습니다. `multi-user`, `oauth` 또는 `oauth-proxy` 모드에서는 설정하면 안 됩니다(호스팅 세션은 세션별로 `x-harness-appsec-api-key`를 제공합니다).
`HARNESS_APPSEC_BASE_URL`	아니요	`https://api.traceable.ai`	`appsec_` 리소스에 사용하는 Traceable GraphQL API 기본 URL. 로컬 개발에서 HTTP URL을 사용하려면 `HARNESS_ALLOW_HTTP=true`가 필요합니다.
`HARNESS_APPSEC_UI_URL`	아니요	`https://app.traceable.ai`	`appsec_` 리소스의 딥 링크에 사용하는 Traceable 웹 UI 기본 URL(설정하지 않으면 `HARNESS_APPSEC_BASE_URL`에서 자동으로 파생됨)
`HARNESS_ORG`	아니요	--	조직 ID. 도구 호출별로 `org_id`를 지정하지 않은 경우 사용됩니다. 생략하면 `org_id`을 명시적으로 제공해야 합니다. 에이전트는 `harness_list(resource_type="organization")`을 통해 조직을 동적으로 검색할 수도 있습니다.
`HARNESS_PROJECT`	아니요	--	프로젝트 ID. 도구 호출별로 `project_id`를 지정하지 않은 경우 사용됩니다. 에이전트는 `harness_list(resource_type="project")`을 통해 프로젝트를 동적으로 검색할 수도 있습니다.
`HARNESS_API_TIMEOUT_MS`	아니요	`30000`	HTTP 요청 시간 제한(밀리초)
`HARNESS_MAX_RETRIES`	아니요	`3`	일시적 오류(429, 5xx)에 대한 재시도 횟수
`HARNESS_MAX_BODY_SIZE_MB`	아니요	`10`	`http` 전송의 최대 HTTP 요청 본문 크기(MB)
`HARNESS_RATE_LIMIT_RPS`	아니요	`10`	Harness API에 대한 클라이언트 측 요청 제한(초당 요청 수)
`LOG_LEVEL`	아니요	`info`	로그 상세 수준: `debug`, `info`, `warn`, `error`
`HARNESS_TOOLSETS`	아니요	(기본값)	쉼표로 구분된 툴셋 목록. 비어 있으면 기본 툴셋을 불러옵니다. `+name`을 사용해 선택적 툴셋을 명시적으로 포함하고 `-name`을 사용해 기본 툴셋을 제거할 수 있습니다(툴셋 필터링 참조).
`HARNESS_READ_ONLY`	아니요	`false`	모든 변경 작업(생성, 업데이트, 삭제, 실행)을 차단합니다. 목록 조회와 가져오기만 허용됩니다. 공유/데모 환경에 유용합니다.
`HARNESS_SCHEMA_MODE`	아니요	`compact`	`compact`(기본값) 또는 `full`. Compact는 도구별 리소스 유형 열거형을 일반 문자열로 바꾸고 필드 설명을 줄여 모델에 전송되는 도구 목록을 약 절반으로 줄입니다(`docs/schema-budget.md` 참조). 유형은 `harness_describe`을 통해 검색됩니다. 모든 리소스 유형을 인라인으로 포함하려면 `full`을 설정하세요.
`HARNESS_AUTO_APPROVE_RISK`	아니요	`none`	자율 워크플로의 위험 기반 자동 승인 임계값. 이 위험 수준 이하의 작업은 확인 없이 진행됩니다. 값: `none`, `low_write`, `medium_write`, `high_write`, `all`. 사용자 확인 요청을 참조하세요.
`HARNESS_SKIP_ELICITATION`	아니요	`false`	지원 중단 예정 — 대신 `HARNESS_AUTO_APPROVE_RISK=all`을 사용하세요. 이전 버전과의 호환성을 위해 유지됩니다
`HARNESS_ALLOW_HTTP`	아니요	`false`	HTTPS가 아닌 `HARNESS_BASE_URL`을 허용합니다. 기본적으로 서버는 보안을 위해 HTTPS를 적용합니다. TLS를 사용하지 않는 Harness 인스턴스에 로컬 개발 환경에서 연결할 때만 `true`로 설정하세요
`HARNESS_PIPELINE_VERSION`	아니요	`0`	(알파) 파이프라인 YAML 버전입니다. `0`은 `pipeline` 리소스 유형을 로드하고 `pipeline_v1`을 제외합니다. `1`은 `pipeline_v1`을 로드하고 `pipeline`을 제외합니다. HTTP 세션은 초기화 시 `x-harness-pipeline-version: 0` 또는 `1`로 이 값을 재정의할 수 있습니다
`HARNESS_MCP_ALLOWED_HOSTS`	아니요	--	HTTP 전송의 Host 헤더 검증에서 허용되는 쉼표로 구분된 호스트 이름입니다. 로컬호스트 바인딩에서는 기본적으로 `mcp.harness.io`이 허용됩니다. 프록시/사용자 지정 도메인은 여기에 추가하세요
`HARNESS_MCP_AUTH_TOKEN`	아니요	--	설정된 경우 `/mcp` HTTP 경로에 필요한 정적 Bearer 토큰입니다. 기본적으로 루프백이 아닌 단일 사용자 및 다중 사용자 바인딩에 필요합니다. `oauth` 모드에서는 설정하지 않아야 합니다
`HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP`	아니요	`false`	루프백이 아닌 바인딩에서 인증되지 않은 HTTP 전송을 명시적으로 허용합니다. 다른 인증된 제어 수단 뒤에서만 사용하세요
`HARNESS_MCP_TRUST_PROXY`	아니요	`0`	클라이언트 IP 확인을 위해 신뢰할 역방향 프록시/로드 밸런서 홉 수입니다(Express `trust proxy`). 서버 앞에 있는 프록시 수로 설정하면 IP별 속도 제한이 프록시 소켓 피어가 아닌 실제 클라이언트를 기준으로 적용됩니다
`HARNESS_MCP_LOG_FILE`	아니요	`~/.claude/harness-mcp.log`	stderr를 더 이상 사용할 수 없을 때 stdio 연결 해제/충돌 진단에 사용하는 파일입니다
`HARNESS_LOG_UNSAFE_BODIES`	아니요	`false`	로그에 원시 요청/응답 본문을 포함합니다. 본문에 비밀 정보가 포함될 수 있으므로 기본적으로 꺼져 있습니다. 로컬 디버깅에만 사용하세요
`HARNESS_AUDIT_FILE`	아니요	--	지속적인 로컬 수집을 위해 줄바꿈으로 구분된 JSON 파일에 감사 이벤트를 추가합니다
`HARNESS_AUDIT_WEBHOOK_URL`	아니요	--	일괄 처리된 감사 이벤트를 수신하는 HTTPS 엔드포인트입니다. 로컬 개발에서 HTTP URL을 사용하려면 `HARNESS_ALLOW_HTTP=true`이 필요합니다
`HARNESS_AUDIT_WEBHOOK_TOKEN`	아니요	--	감사 웹훅에 전송되는 선택적 Bearer 토큰입니다
`HARNESS_AUDIT_WEBHOOK_BATCH_SIZE`	아니요	`10`	웹훅을 플러시하기 전에 일괄 처리할 감사 이벤트 수입니다
`HARNESS_AUDIT_WEBHOOK_FLUSH_MS`	아니요	`5000`	웹훅을 플러시하기 전까지 감사 이벤트를 보관할 최대 시간입니다
`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`	아니요	`3`	실패한 단계의 로그를 가져올 때 `harness_diagnose`이 시작하는 로그 블롭 다운로드의 최대 동시 실행 수입니다. 진단 지연의 대부분이 로그 가져오기 소요 시간이고 파드에 메모리 여유가 있는 경우에만 늘리세요

시맨틱 검색

harness_search은 시맨틱 라우팅을 사용해 Harness로 요청을 분산하기 전에 scatter-gather API 호출 범위를 좁힙니다. 세 가지 검색 공급자를 사용할 수 있습니다.

공급자	사용 시기
`local` (기본값)	단일 사용자 stdio 모드. `@huggingface/transformers`를 통해 `all-MiniLM-L6-v2`을 프로세스 내에서 실행합니다. 처음 사용할 때 약 23 MB 크기의 모델을 다운로드하며, 이후 시작 시에는 캐시를 사용합니다.
`remote`	다중 사용자 HTTP 모드(Harness 호스팅). 임베딩과 검색을 외부 검색 서비스에 위임합니다. 테넌트 격리는 `tenant_id`을 통해 적용됩니다. 정적 지식/문서에는 `global`을 사용하고, 계정별 엔터티 데이터에는 계정 ID를 사용합니다.
`none`	시맨틱 검색을 완전히 비활성화합니다. 모든 리소스 유형을 대상으로 키워드 scatter-gather를 수행합니다.

원격 공급자 구성:

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

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

포함된 스텁 서비스를 사용해 원격 공급자를 로컬에서 테스트할 수 있습니다(외부 종속성 없음).

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

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

# 3. Build the MCP server
pnpm build

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

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

스텁(stub-search-service.py)은 프로덕션 검색 서비스와 동일한 /v1/health, /v1/ingest, /v1/search 계약을 구현합니다. 모델을 다운로드할 필요가 없도록 간단한 문자 집합 임베딩을 사용하므로, 결과는 의미상 그럴듯하지만 프로덕션 품질은 아닙니다.

HTTPS 적용

HARNESS_BASE_URL은 기본적으로 HTTPS를 사용해야 합니다. HTTPS가 아닌 URL(예: http://localhost:8080)을 설정하면 서버는 다음 메시지와 함께 시작을 거부합니다.

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

감사 로깅

레지스트리를 통해 디스패치되는 모든 Harness API 작업(list, get, create, update, delete, execute)은 감사 싱크가 구성된 경우 구조화된 감사 이벤트를 생성합니다. 변경 이벤트에는 확인 컨텍스트가 있을 때 elicitation 또는 자동 승인에 사용된 확인 경로가 포함됩니다. 읽기 이벤트에는 현재 확인 메타데이터가 포함되지 않습니다. 레지스트리를 우회하는 로컬 메타데이터 및 스키마 검색 도구(예: harness_describe, harness_schema)는 이 감사 스트림에 포함되지 않습니다. 기본적으로 stderr 싱크가 등록되지만 일반 로거를 거치며 LOG_LEVEL을 따릅니다. 감사 데이터를 지속적으로 수집하려면 파일 또는 웹훅 싱크를 구성하세요.

HARNESS_AUDIT_FILE은 로컬 수집을 위해 줄바꿈으로 구분된 JSON 이벤트를 추가합니다.
HARNESS_AUDIT_WEBHOOK_URL은 { "events": [...] } 배치를 HTTPS 웹훅으로 전송하며, 선택적으로 HARNESS_AUDIT_WEBHOOK_TOKEN를 사용할 수 있습니다. 실패한 배치는 제한된 용량의 큐에 다시 추가되며, 도구 실행을 차단하는 대신 경고와 함께 결국 삭제됩니다.
선택적 OpenTelemetry 피어 종속성이 설치되어 있으면 OTEL_EXPORTER_OTLP_ENDPOINT이 감사 스팬을 활성화합니다. 싱크는 등록된 트레이서 공급자가 있으면 이를 재사용하고, 없으면 독립형 OTLP 내보내기를 초기화합니다.

각 이벤트에는 도구 이름, 리소스 유형, 작업, 식별자, 타임스탬프, 위험도, 결과, HTTP 메서드/경로, 소요 시간, 해당하는 경우 확인 방법이 포함됩니다. 감사 싱크는 최선형 텔레메트리입니다. 전송 문제는 로그에 기록되며, 기본 Harness API 작업을 재시도하거나 변경하지 않습니다. OTel 설정 세부 정보와 스팬 속성은 specs/005-otel-audit-sink.md을 참조하세요.

도구 참조

서버는 MCP 도구 11개를 노출합니다. 대부분의 API 도구는 선택적 재정의 값으로 org_id 및 project_id을 받습니다. 생략하면 HARNESS_ORG 및 HARNESS_PROJECT을 사용합니다. harness_describe는 로컬 메타데이터만 다루며 조직/프로젝트 범위를 사용하지 않습니다.

URL 지원: 대부분의 API 관련 도구는 url 매개변수를 받습니다. Harness UI URL을 붙여 넣으면 서버가 조직, 프로젝트, 리소스 유형, 리소스 ID, 파이프라인 ID, 실행 ID를 자동으로 추출합니다. harness_describe은 url를 받지 않습니다.

범위 지원: 계정/조직/프로젝트 변형이 있는 리소스 유형은 harness_describe에서 supportedScopes을 노출합니다. 특정 수준이 필요하면 resource_scope를 전달하세요.

resource_scope: "account"은 accountIdentifier만 전송합니다.
resource_scope: "org"은 accountIdentifier 및 orgIdentifier을 전송합니다.
resource_scope: "project"은 계정, 조직, 프로젝트 식별자를 전송합니다.

현재 여러 범위를 지원하는 리소스는 connector, service, environment, infrastructure, secret, file_store, template, policy, policy_set입니다. resource_scope을 생략하면 레지스트리는 리소스의 기본 범위와 구성된 기본값을 사용합니다. 단, 선택적 범위로 표시된 리소스는 명시적으로 전달하지 않는 한 조직/프로젝트 범위를 생략할 수 있습니다. 경로에 계정 수준 또는 프로젝트 수준 컨텍스트가 포함된 경우 Harness URL로 범위를 자동 설정할 수도 있습니다.

구조화된 출력: 모든 도구는 MCP outputSchema을 선언합니다. harness_list은 목록 형태의 Harness 응답을 객체 형태의 구조화된 콘텐츠로 정규화하여 엄격한 클라이언트가 이를 검증할 수 있도록 합니다. 최상위 배열은 { "items": [...], "total": <count>, "page": <page> }가 되고, content, data, body, objects, features와 같은 일반적인 래퍼 키는 필요한 경우 items으로 끌어올립니다. 텍스트 응답에는 모든 클라이언트에 반환되는 간결한 JSON 페이로드가 계속 포함됩니다.

도구	설명
`harness_describe`	사용 가능한 리소스 유형, 작업 및 필드를 검색합니다. API 호출 없이 로컬 레지스트리 메타데이터를 반환합니다.
`harness_schema`	리소스 생성/업데이트에 필요한 정확한 YAML/JSON Schema 정의와 예시를 가져옵니다. 파이프라인/템플릿 스키마는 번들로 제공되며, 커넥터, 환경, 서비스, 시크릿 및 인프라 스키마는 범위 인식 엔터티 스키마로, 번들 스냅샷 또는 NG `/yaml-schema`에서 가져옵니다. `release_process` 및 `release_activity` 스키마는 RMG `/api/yamlSchema`에서 실시간으로 가져옵니다. `path`을 통해 심층 탐색을 지원합니다.
`harness_list`	필터링, 검색 및 페이지네이션을 사용해 지정된 유형의 리소스를 나열합니다.
`harness_get`	식별자로 단일 리소스를 가져옵니다.
`harness_create`	새 리소스를 생성합니다. 인라인 및 원격(Git 기반) 파이프라인을 지원합니다. elicitation을 통해 사용자 확인을 요청합니다.
`harness_update`	기존 리소스를 업데이트합니다. 인라인 및 원격(Git 기반) 파이프라인을 지원합니다. elicitation을 통해 사용자 확인을 요청합니다.
`harness_delete`	리소스를 삭제합니다. elicitation을 통해 사용자 확인을 요청합니다. 파괴적인 작업입니다.
`harness_execute`	리소스에 대한 작업을 실행합니다(파이프라인 실행/재시도, Git에서 파이프라인 가져오기, 플래그 전환, 앱 동기화). elicitation을 통해 사용자 확인을 요청합니다. 파이프라인 실행에는 아래의 런타임 입력 워크플로를 사용합니다(`branch`/`tag`/`pr_number`/`commit_sha` 약식 확장 지원).
`harness_search`	단일 쿼리로 Harness 리소스 유형 전체를 검색합니다. 의미 기반 라우팅(로컬 `all-MiniLM-L6-v2` ONNX 임베딩, 384차원)을 사용해 시작 시 색인된 `knowledge` 코퍼스에서 관련 리소스 유형을 예측합니다. 일반적으로 분산 수집 전에 약 163개 유형을 1~8개로 좁힙니다. 의미 신뢰도가 낮으면 전체 키워드 분산 수집으로 대체합니다. 라우팅이 실행되면 응답에 `semantic_routed` 및 `types_skipped`가 포함됩니다. 새 리소스 유형을 검색 가능하게 만드는 방법은 `docs/search-guidelines.md`을 참조하세요.
`harness_diagnose`	`pipeline`, `connector`, `delegate` 및 `gitops_application` 리소스를 진단합니다(별칭: `execution` -> `pipeline`, `gitops_app` -> `gitops_application`). 파이프라인의 경우 단계/스텝 타이밍과 실패 세부 정보를 반환하고, 커넥터/델리게이트/GitOps 앱의 경우 대상별 상태 및 문제 해결 신호를 반환합니다.
`harness_status`	최근 실행, 실패율 및 상세 링크가 포함된 실시간 프로젝트 상태 대시보드를 가져옵니다.

스키마 조회 워크플로

YAML 기반 리소스를 생성하거나 업데이트하기 전에 harness_schema을 사용하면, 에이전트가 설명문을 보고 추측하는 대신 정확한 필드 이름과 제약 조건을 복사할 수 있습니다.

번들 스키마에는 pipeline, template, trigger, pipeline_v1, template_v1, inputSet_v1, overlayInputSet_v1 및 agent-pipeline가 포함됩니다.
엔터티 스키마에는 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 스키마가 변경되면 유지 관리 담당자는 pnpm sync-entity-schemas를 사용해 벤더 제공 엔터티 스냅샷을 새로 고칠 수 있습니다.

도구 예시

사용 가능한 리소스 검색:

{ "resource_type": "pipeline" }

계정의 조직 나열:

{ "resource_type": "organization" }

조직의 프로젝트 나열:

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

프로젝트의 파이프라인 나열:

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

특정 서비스 가져오기:

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

파이프라인 실행:

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

기능 플래그 전환:

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

모든 리소스 유형 검색:

{ "query": "payment-service" }

ID로 실행 진단(요약 모드 — 기본값):

{ "execution_id": "abc123XYZ" }

Harness URL로 진단:

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

커넥터 연결 진단:

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

델리게이트 상태 진단:

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

GitOps 애플리케이션 진단(옵션 포함):

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

파이프라인의 최신 실행 보고서 가져오기:

{ "pipeline_id": "my-pipeline" }

YAML 및 실패한 스텝 로그를 포함한 전체 진단 모드:

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

로그를 활성화한 요약 모드(두 방식의 장점 결합):

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

프로젝트 상태 가져오기:

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

마이그레이션 유형으로 필터링한 데이터베이스 스키마 나열:

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

스키마의 데이터베이스 인스턴스 나열:

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

스키마 및 인스턴스에 대해 확인된 LLM 작성 파이프라인 가져오기:

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

스키마 인스턴스의 스냅샷 객체 이름(예: 테이블) 나열:

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

지정된 객체의 전체 스냅샷 메타데이터 가져오기:

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

파이프라인 실행 워크플로(권장)

v0 파이프라인의 경우 실행 시점 입력 오류를 줄이려면 다음 순서를 사용하세요.

필수 런타임 입력 검색

harness_get(resource_type="runtime_input_template", resource_id="<pipeline_id>")
반환된 템플릿에는 값이 필요한 <+input> 자리표시자가 표시됩니다.

입력 전략 선택

단순 변수: 평면 키-값 inputs을 전달합니다(예: {"branch":"main","env":"prod"}).
복잡한/구조적 입력: input_set_ids을 사용합니다(CI 코드베이스/빌드 블록 및 중첩 템플릿 입력에 가장 적합).

CI 코드베이스 약식 키(파이프라인 실행 전용):

약식 키	확장된 구조
`branch`	`build.type=branch`, `build.spec.branch=<value>`
`tag`	`build.type=tag`, `build.spec.tag=<value>`
`pr_number`	`build.type=PR`, `build.spec.number=<value>`
`commit_sha`	`build.type=commitSha`, `build.spec.commitSha=<value>`

제약 조건: inputs.build이 이미 있으면 약식 확장을 건너뜁니다(명시적 build이 우선 적용됨).

실행 시작

harness_execute(resource_type="pipeline", action="run", resource_id="<pipeline_id>", ...)
YAML을 기본 브랜치가 아닌 브랜치에서 로드해야 하는 Git 기반 파이프라인의 경우 params.pipeline_branch을 전달합니다(Harness에는 branch로 전송됨). 이 명시적 정의 선택자는 params.branch 별칭보다 우선합니다. inputs.branch은 CI 코드베이스 브랜치를 별도로 선택합니다.
```
{
  "resource_type": "pipeline",
  "action": "run",
  "resource_id": "deploy_app",
  "params": { "pipeline_branch": "feature/new-stage" },
  "inputs": { "branch": "main" },
  "wait": true
}
```

선택 사항: 두 방식 결합

기본 구조에는 input_set_ids을, 단순한 재정의에는 inputs을 사용합니다.

v1 파이프라인의 경우:

harness_get(resource_type="runtime_input_template_v1", resource_id="<pipeline_id>")을 가져옵니다. Git 기반 파이프라인의 경우 branch_name, connector_ref 및 repo_name를 params을 통해 전달합니다.
반환된 각 inputs[].details.name을 harness_execute.inputs의 최상위 키로 사용합니다.
harness_execute(resource_type="pipeline_v1", action="run", resource_id="<pipeline_id>", inputs={...})을 실행합니다. 서버는 이 값들을 inputs: YAML 루트 아래에 래핑하고 API의 inputs_yaml 본문을 전송합니다. 필수 필드가 확인되지 않으면 도구는 예상 키와 권장 입력 세트가 포함된 사전 검사 오류를 반환합니다. harness_describe(resource_type="pipeline") (executeActions.run.inputShorthands)를 사용해 사용 가능한 약칭 매핑을 확인할 수 있습니다.

동적 파이프라인 실행

에이전트나 외부 시스템이 런타임에 전체 v0 파이프라인 YAML을 생성하고 기존 Harness 파이프라인 셸에서 실행해야 하는 경우 pipeline_dynamic_execution.run을 사용합니다. 이는 일반적인 pipeline.run을 대체하지 않습니다. 저장된 v0 파이프라인이 이미 있어야 하고, 계정 수준 및 파이프라인 수준에서 Allow Dynamic Execution이 활성화되어 있어야 하며, 호출자에게 파이프라인에 대한 Edit 및 Execute 권한이 있어야 합니다.

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

제약 사항:

body은 yaml 필드가 있는 객체여야 합니다. 공개 harness_execute 스키마에서는 원시 문자열 본문을 거부합니다.
body.yaml은 YAML 문자열 또는 JSON 파이프라인 객체일 수 있습니다. JSON은 요청 전에 YAML로 직렬화됩니다.
런타임 <+input> 플레이스홀더는 이 API에서 확인되지 않습니다. 모든 값이 확인된 YAML을 제출하세요.
동적 실행 엔드포인트에서는 입력 세트, 선택적 단계 실행, 재시도 및 트리거를 지원하지 않습니다.
이 작업은 high_write이며 일반적인 확인/자동 승인 경로를 사용합니다. 응답은 API 봉투를 { "execution_id": "...", "status": "..." }로 투영하고, 범위 데이터를 사용할 수 있는 경우 openInHarness 실행 링크를 포함합니다.

Harness에서 실행이 활성화되지 않았다고 거부하면 계정 수준의 Allow Dynamic Execution 설정과 Pipeline -> Advanced Options -> Dynamic Execution Settings 아래의 파이프라인 수준 토글을 모두 확인하세요.

실행 입력 포렌식

실행 후 execution_inputs을 사용하면 특정 실행을 생성한 병합 입력 YAML을 검사할 수 있습니다. 입력 세트 병합, Git 기반 입력 세트 브랜치 또는 실행 페이지에서만으로는 재구성하기 어려운 트리거/런타임 값에 따라 실패가 달라지는 경우 유용합니다.

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

get 응답은 다음 항목으로 투영됩니다.

executionId - resource_id의 계획 실행 ID.
inputSetYaml - 실행에 사용된 병합 런타임 입력 YAML 또는 null.
inputSetTemplateYaml - 실행 시점의 입력 템플릿 또는 null.
resolvedYaml - resolve_expressions=true인 경우 표현식이 확인된 YAML이며, 그렇지 않은 경우 대개 null입니다.
inputSetDetails - 기여한 저장된 입력 세트를 { identifier, name } 쌍으로 표시합니다.
inputSetBranchName - Git 기반 입력 세트의 소스 브랜치 또는 null.

execution_inputs은 get 전용이며 읽기 위험 작업입니다. 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 Agent에 파이프라인 생성을 요청합니다:

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

자연어로 서비스를 업데이트합니다:

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

파이프라인 저장 모드

Harness 파이프라인은 세 가지 방식으로 저장할 수 있습니다:

모드	설명	사용 시점
Inline	파이프라인 YAML을 Harness에 저장	기본값. 가장 간단한 설정이며 Git이 필요하지 않습니다.
Remote (External Git)	파이프라인 YAML을 GitHub, GitLab, Bitbucket 등에 저장	외부 공급자를 사용해 Git 기반 파이프라인을 코드로 관리하는 팀.
Remote (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"
  }
}

원격 파이프라인 생성(External 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"
}

리소스 유형

44개 도구 세트에 걸쳐 274개의 리소스 유형이 구성되어 있습니다. 각 리소스 유형은 CRUD 작업의 일부와 선택적 실행 작업을 지원합니다.

플랫폼

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`organization`	x	x	x	x	x
`project`	x	x	x	x	x

파이프라인

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`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 에이전트

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`agent`	x	x	x	x	x
`agent_run`	x

서비스

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`service`	x	x	x	x	x

환경

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`environment`	x	x	x	x	x	`move_configs`

커넥터

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`connector`	x	x	x	x	x	`test_connection`
`connector_catalogue`	x
`llm_model`	x

인프라

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`infrastructure`	x	x	x	x	x	`move_configs`

시크릿

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`secret`	x	x

실행 로그

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`execution_log`		x

감사 추적

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`audit_event`	x	x

Delegate

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`delegate`	x	x
`delegate_token`	x	x	x		x	`revoke`, `get_delegates`

코드 저장소

리소스 유형	List	Get	Create	Update	Delete	실행 작업
`repository`	x	x	x	x
`branch`	x	x	x		x
`commit`	x	x	x			`diff`, `diff_stats`
`file_content`	x	x				`blame`
`tag`	x		x		x
`repo_rule`	x	x
`space_rule`	x	x

commit 생성은 복제 없이 Harness Code API를 통해 하나 이상의 파일 작업을 직접 커밋합니다. body.title, body.branch, body.actions을 전달하세요. 각 작업은 CREATE, UPDATE, DELETE, MOVE 중 하나이며, UPDATE에는 현재 blob SHA가 필요합니다.

file_content list는 ref의 모든 경로를 반환하고, get은 파일 또는 디렉터리 콘텐츠를 반환합니다(저장소 루트의 경우 path을 생략하거나 빈 값으로 전달하고, 중첩 경로에는 슬래시를 유지합니다). 저장소의 기본 브랜치를 사용하려면 git_ref을 생략하세요. main을 추측하지 마세요.

아티팩트 레지스트리

리소스 유형	목록	조회
`registry`	x	x
`artifact`	x
`artifact_version`	x
`artifact_file`	x

파일 저장소

리소스 유형	목록	조회	생성	수정	삭제	액션 실행
`file_store`	x	x	x	x	x	`list_children`

file_store는 일반 도구를 통해 Harness 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"})

멀티파트 본문 제약 사항:

생성/수정은 JSON body를 받은 다음 /ng/api/file-store을 위해 multipart/form-data로 변환합니다.
name, type(FILE 또는 FOLDER), 그리고 parent_identifier은 필수입니다. 선택한 범위의 루트에만 리터럴 "Root"을 사용하세요.
FILE 생성은 content(UTF-8 문자열) 또는 content_base64(유효한 비어 있지 않은 base64) 중 정확히 하나가 필요합니다. FILE 수정은 메타데이터만 수정하는 경우 콘텐츠를 생략할 수 있으며, 콘텐츠를 교체하려면 콘텐츠 필드를 정확히 하나 제공해야 합니다.
FOLDER 생성/수정은 content과 content_base64를 생략해야 합니다.
선택적 file_usage은 MANIFEST_FILE, CONFIG, 또는 SCRIPT이어야 하며, description, mime_type, path, tags과 같은 선택적 스칼라 메타데이터는 문자열이어야 합니다.
업로드 콘텐츠는 최대 100 MB로 제한됩니다. 확인 프롬프트는 유도 전에 content, content_base64, contentBase64 미리보기를 가립니다.

list_children은 축약형(resource_id와 params.folder_name, 또는 params.file_store_id/params.folder_identifier와 params.folder_name) 또는 identifier, name, type: "FOLDER"을 포함한 전체 FileStoreNode body을 허용합니다. 전체 본문은 Harness 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

Database 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

Infrastructure as Code Management (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이므로 선택적 필드에는 get-then-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="...")으로 생성/수정된 워크스페이스를 가져옵니다.
재사용 가능한 Terraform/env 변수 세트에는 iacm_variable_set에서 (선택적으로 resource_scope와 함께) harness_list / harness_create / harness_update을 사용합니다. 응답은 VariableSet 리소스입니다.
모듈 레지스트리에는 iacm_module에서 harness_list / harness_create / harness_update을 사용합니다(name + system 필수, 조직 또는 프로젝트 범위 모듈의 경우 org_id/project_id와 함께 resource_scope 추가). 응답은 모듈 리소스입니다.
계정 프로바이더 레지스트리에는 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부터 시작하는 페이지를 계속 요청하고, 총계가 필요하면 페이지 개수를 합산하세요.

Internal Developer Portal (IDP)

리소스 유형	목록	조회	액션 실행
`idp_entity`	x	x
`scorecard`	x	x
`scorecard_check`	x	x
`scorecard_stats`		x
`scorecard_check_stats`		x
`idp_score`	x	x
`idp_workflow`	x		`execute`
`idp_tech_doc`	x

풀 리퀘스트

리소스 유형	목록	조회	생성	수정	삭제	액션 실행
`pull_request`	x	x	x	x		`close`, `merge`
`pr_reviewer`	x		x			`submit_review`
`pr_comment`			x	x	x	`resolve`, `unresolve`
`pr_check`	x
`pr_activity`	x

명시적 닫기 작업에는 harness_execute(resource_type="pull_request", action="close", ...)을 사용하세요. harness_update은 body.state(open 또는 closed)도 허용하며 상태 변경을 전용 Harness Code PR 상태 엔드포인트로 라우팅합니다. 제목/설명 편집은 별도의 수정 호출로 보내세요.

PR 댓글을 읽으려면 harness_list(resource_type="pr_activity", filters={type: ["comment", "code-comment"]}, ...)를 사용하세요. 댓글 쓰기 작업에는 pr_comment을 사용하세요.

댓글 스레드를 해결하려면 harness_execute(resource_type="pr_comment", action="resolve", ...)을, 다시 열려면 action="unresolve"을 사용하세요. 둘 다 본문을 받지 않습니다. comment_id는 pr_activity에서 해당 행의 parent_id가 null인 행의 id이어야 하며, API는 답글 ID를 거부합니다.

릴리스 관리

릴리스 관리(RMG) 리소스는 기본적으로 활성화되어 있습니다. 정의 리소스(release_process, release_activity)는 body.yaml과 함께 목록/조회/생성/수정/삭제를 지원하며, 생성/수정 전에 harness_schema(resource_type="release_process"|"release_activity")을 호출하세요. 실행 리소스는 실행 중인 릴리스를 모니터링합니다. 대부분의 목록 작업에는 release_id이 필요합니다(harness_list resource_type=release의 UUID 또는 identifier-1.0.0-abc과 같은 UI URL 슬러그). RMG 릴리스 URL을 harness_list에 붙여넣으면 release_id가 자동으로 채워집니다.

RMG 호출은 Harness-Account 헤더를 통한 계정 범위 지정과 함께 ${HARNESS_BASE_URL}/gateway/rmg을 사용합니다. 조직/프로젝트 범위는 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)을 사용한 다음, body.yaml과 함께 harness_create / harness_update를 사용합니다.
활성 또는 최근 릴리스를 찾으려면 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_execution_task 및 release_execution_activity에도 동일한 release_id을 사용합니다.
각 리소스에 문서화된 대로 release_id과 params.phase_identifier / params.activity_identifier / activity_execution_id를 사용해 release_input, release_execution_phase_input, release_execution_phase_output, release_execution_activity_output 또는 release_execution_activity_input에서 harness_get을 실행합니다.

통합 검색

선택적으로 활성화하는 unified-search 도구 세트(HARNESS_TOOLSETS=+unified-search)는 search-service가 제공하는 모든 소스에서 의미 기반 검색을 추가합니다. 결과는 호출자의 계정으로 범위가 제한되고 RBAC 필터링이 적용됩니다. 계정에 의미 검색 기능 플래그가 필요합니다.

리소스 유형	목록	가져오기	작업 실행
`unified_search`	x		`search`
`unified_search_source`		x

# 1. Search with the user's words (all sources)
harness_search(query="payments service that keeps crashing")

# 2. Optional: if a hit names a Knowledge Graph type, look it up or query it
harness_get(resource_type="kg_type", resource_id="<type id>", params={kind: "<kind>"})

# 3. Narrow with filters on the hits' metadata keys, per source
harness_execute(resource_type="unified_search", action="search", body={
  query: "payments service that keeps crashing",
  source_filters: {"<source>": {predicate: {field: "<metadata key>", op: "NE", values: [{string_value: "closed"}]}}}
})

harness_get(resource_type="unified_search_source")는 소스를 나열합니다. 필터 구문은 harness_describe(resource_type="unified_search")을 참조하세요.

이는 의미 검색의 의미 라우팅 공급자와 별개입니다. 해당 공급자는 MCP 리소스 정의와 문서를 인덱싱하여 harness_search의 팬아웃 범위를 좁힙니다.

Vibe

기본적으로 활성화되는 vibe 도구 세트는 ${HARNESS_BASE_URL}/vibe/v1 아래의 Vibe Orchestrator BFF 계약을 다룹니다. 기존 Harness 연결과 계정 헤더를 사용하며, 요청 본문에 계정/조직/프로젝트 쿼리 매개변수나 범위 필드를 추가하지 않습니다. 팀은 Harness API 키 인증(PAT/SAT)을 사용해 Vibe 흐름을 검증했으므로 기본 세션에는 선택적 설정이 필요하지 않습니다. 엄선된 OpenAPI 문서는 bearer/session 인증을 설명하며, 서버의 OAuth 모드는 현재 세션의 bearer 토큰을 전달합니다. 자동 회귀 테스트는 두 헤더 경로를 모두 검증합니다. 게이트웨이 인증은 대상 환경의 구성에 따라 달라집니다.

리소스 유형	목록	가져오기	생성	업데이트	삭제	작업 실행
`vibe_project`			x			`prepare`, `deploy`
`vibe_app_lifecycle`		x				`events`

API는 두 가지 입력 경로를 지원합니다. 다음 API 고유 요청 형식을 유지하세요.

코딩 에이전트에서 사용할 수 있는 소스	API 흐름
GitHub 저장소 링크/커넥터	`resource_type="vibe_project"` 및 `body.mode`과 모드별 필드를 사용해 `harness_create`를 호출합니다. 계약에는 `github_link` 및 `github_connector`가 명시되어 있지만 URL, 브랜치 또는 커넥터 필드 형식은 정의되어 있지 않습니다. 이 필드는 매핑을 임의로 만들지 않고 백엔드로 전달됩니다.
ZIP 파일	앱 이름과 파일 메타데이터를 사용해 `prepare`을 호출하고, 반환된 서명된 대상에 바이트를 업로드한 다음 `deploy`을 호출합니다.
로컬 소스 디렉터리	코딩 에이전트가 의도한 작업 공간 소스를 로컬에서 ZIP으로 압축한 다음 ZIP 흐름을 따릅니다. 로컬 경로나 대화 컨텍스트는 API에서 지원하는 소스 업로드 방식이 아닙니다.

디렉터리를 패키징할 때는 빌드에 필요한 소스, 매니페스트, 잠금 파일, 구성 및 의도한 미커밋 편집 내용을 포함하세요. 자격 증명, .git, 설치된 종속성 및 생성된 아티팩트는 제외하세요. 패키징과 서명된 업로드는 파일에 접근할 수 있는 곳에서 수행됩니다. 호스팅된 MCP 서버는 코딩 에이전트의 로컬 디렉터리를 읽을 수 없습니다.

기존 ZIP의 업로드를 준비하려면 다음을 수행합니다.

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

이 값을 harness_execute에 전달합니다. 크기는 실제 ZIP의 크기여야 합니다. size_bytes, content_type 및 md5은 선택 사항이며 null일 수 있습니다. OpenAPI에서 허용하는 추가 준비 필드는 백엔드 검증을 위해 보존됩니다. 준비 작업은 각 파일의 uploadUrl, method, headers 및 expiresAt을 포함해 projectId, sourceId 및 upload를 반환합니다. 반환된 서명된 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 이벤트 또는 5초 동안 소비하며, 응답 제한은 1MiB입니다. 이러한 제한은 Vibe 엔드포인트에 적용됩니다. 연결의 HARNESS_API_TIMEOUT_MS도 연결과 스트림 소비를 함께 제한하며, 만료되면 시간 초과 오류가 반환됩니다. 완료된 배치는 events 및 stop_reason(end, event_limit 또는 duration_limit)을 반환하고 스트림을 닫습니다. 초기 연결 실패와 스트림 중단은 모두 재시도되지 않습니다. 이벤트는 문서화된 재생 커서가 없는 일시적인 차이 정보입니다. 권위 있는 스냅샷을 확인하려면 수명 주기 가져오기를 사용하세요. 두 수명 주기 읽기 작업은 모두 읽기 전용 모드에서 사용할 수 있습니다.

기능 플래그

리소스 유형	목록	가져오기	생성	업데이트	삭제	작업 실행
`fme_workspace`	x
`fme_environment`	x	x	x	x	x
`fme_feature_flag`	x	x	x	x	x	`kill`, `restore`, `reallocate`, `archive`, `unarchive`
`fme_feature_flag_definition`	x	x	x	x	x	`kill`, `restore`, `reallocate`
`fme_rollout_status`	x
`fme_rule_based_segment`	x	x	x		x
`fme_rule_based_segment_definition`	x			x		`enable`, `disable`, `change_request`
`fme_traffic_type`	x
`fme_identity`			x	x
`fme_standard_segment`	x	x
`fme_segment_keys`	x			x
`fme_segment`	x	x	x	x	x
`fme_segment_definition`	x	x	x	x	x	`list_keys`, `add_keys`, `remove_keys`
`fme_metric`	x	x	x	x	x
`fme_event_type`	x	x
`fme_experiment`	x	x	x	x	x
`fme_experiment_settings`		x		x	x
`fme_experiment_alerting`		x		x
`fme_experiment_result`	x

FME(Split.io) 리소스 — fme_* 리소스는 이중 모드 범위 지정을 지원합니다. 레거시 호출은 workspace_id를 전달해 Split.io API(api.split.io)를 호출합니다. 최신 호출은 org_id+project_id을 함께 전달해 Harness 네이티브 엔드포인트(표준 HARNESS_API_KEY/HARNESS_BASE_URL, 다른 모든 harness_* 리소스와 동일한 인증)를 호출합니다. 같은 호출에서 workspace_id과 org_id/project_id을 모두 전달하거나, org_id와 project_id만 함께 사용하는 것은 오류입니다. 호출마다 한 가지 모드를 선택하세요. 아래의 모든 작업은 리소스가 Harness 네이티브 전용으로 표시되지 않는 한 레거시 모드에서 변경 없이 사용할 수 있습니다. Harness 네이티브 모드의 지원 범위는 현재 더 좁습니다.

fme_workspace — Harness 네이티브에 해당하는 기능이 없습니다. 레거시 전용입니다(workspace_id 값을 검색하는 데 사용).
fme_environment — 이중 모드 list(workspace_id 또는 org_id+project_id). get/create/update/delete은 Harness 네이티브 전용(/fme/api/v4/environments)입니다. MCP에는 해당 작업을 위한 workspace_id 계약이 없었습니다. 네이티브 목록은 선택적 offset/limit을 사용합니다(최대 100개, harness_list size은 limit에 매핑됨). 봉투 {data, limit, offset, totalCount}는 items/total으로 승격됩니다. 네이티브 생성/업데이트는 isProduction을 사용합니다(production은 별칭으로 허용됨). 네이티브 업데이트는 JSON Merge Patch입니다. name 및 isProduction은 지울 수 없습니다. 이름은 최대 15자입니다.
fme_feature_flag — 이중 모드이며 두 분기 모두 완전히 연결되어 있습니다. Harness 네이티브(org_id+project_id): list/get/create/delete은 /fme/api/v4/feature-flags을 호출합니다(create의 본문: name, trafficType, 선택적 description/tags/owners, CreateFeatureFlagRequest 기준). update은 /fme/api/v4/feature-flags/{name}에 병합 패치를 보냅니다. archive/unarchive는 /fme/api/v4/feature-flags/{name}/archive|unarchive을 호출합니다(선택적 comment만 해당 — title는 없음, ArchiveUnarchiveRequest 기준). kill/restore/reallocate은 environment_id을 쿼리 매개변수로 사용해 /fme/api/v4/feature-flag-definitions/{name}/kill|restore|reallocate을 호출합니다(선택적 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이 필요합니다. 종료/복원/재할당은 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 참조.) 모든 작업(list/get/create/delete)에서 Harness 네이티브 모드가 거부됩니다. 대신 fme_segment를 사용하세요. 이 리소스는 레거시 workspace_id 계약만 지원합니다.
fme_rule_based_segment_definition — (지원 중단됨 — fme_segment_definition 참조.) 모든 작업/액션(list/update/enable/disable/change_request)에서 Harness 네이티브 모드가 거부됩니다. 대신 fme_segment_definition을 사용하세요(여기에는 enable/disable/change_request에 해당하는 기능이 없음). 이 리소스는 레거시 workspace_id/environment_id 계약만 지원합니다.
fme_traffic_type — 이중 모드 list. org_id+project_id(권장) 또는 더 이상 사용되지 않는 workspace_id을 전달합니다. 네이티브 페이지 매김은 offset/limit을 사용합니다(최대 100개, harness_list size는 limit에 매핑됨). 결과는 items/total로 승격됩니다. 각 항목에는 id 및 name이 있습니다(displayAttributeId은 없음).
fme_identity — org_id+project_id을 함께 전달하면 create/update는 아직 구현되지 않았습니다. 그렇지 않으면 일반 레거시 호출로 진행됩니다.
fme_standard_segment — 지원 중단되었습니다. 레거시 workspace_id은 여전히 Split v2를 호출합니다. Harness 네이티브는 거부됩니다. 대신 fme_segment를 사용하세요.
fme_segment_keys — list/update는 레거시로 유지됩니다(workspace_id / environment_id+segment_name). Harness 네이티브(org_id+project_id)는 거부됩니다. 대신 fme_segment_definition execute list_keys/add_keys/remove_keys을 사용하세요.
fme_segment — 네이티브 전용(org_id+project_id). CRUD. list/get/update/delete에는 segment_type가 필요합니다: STANDARD | LARGE | RULE_BASED. 생성 본문: name, trafficType, segmentType; 선택적 description, tags, owners.
fme_segment_definition — 네이티브 전용. CRUD 및 execute 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에 매핑됨). 백엔드 CreateMetricRequest에서는 선택 사항(기본값 PER)이지만 create에는 spread이 필요합니다. 이를 생략하면 RATE 메트릭의 의미가 조용히 바뀌므로 MCP 측에서만 더 엄격한 계약을 적용합니다. update은 JSON Merge Patch입니다. name/trafficType은 변경할 수 없으며 허용되지 않습니다. delete는 영구 하드 삭제이며(보관/복원 없음) destructive로 분류됩니다.
fme_event_type — Harness 네이티브 전용(레거시 workspace_id 지원 없음). 읽기 전용입니다: list/get는 /fme/api/v4/event-types에 연결되어 있습니다. id은 이벤트 이름입니다. 최근 30일 동안 이벤트가 있었던 이벤트 유형만 표시됩니다. 요청하는 워크스페이스의 트래픽 유형 범위 밖에 있거나 30일 넘게 유휴 상태인 이벤트 유형에 대해 get는 404를 반환합니다. 목록 필터: name(부분 문자열), traffic_type(ID 또는 이름 기준), offset/limit(harness_list size은 limit에 매핑됨). ID를 추측하는 대신 이를 사용해 실제 이벤트 유형 ID를 확인한 다음 fme_metric의 baseEventTypes/filterEventType 또는 event_type_ids 필터에서 참조하세요.
fme_experiment — Harness 네이티브 전용(레거시 workspace_id 지원 없음). CRUD는 /fme/api/v4/experiments에 연결되어 있습니다. list에는 parent_type이 필요합니다(FEATURE_FLAG, AI_CONFIG; CONFIG은 404를 반환함). status을 전달하지 않으면 기본값은 ACTIVE 실험입니다. create에는 environment_id(쿼리 매개변수)와 본문의 parent/name/startAt/endAt/baselineTreatment/comparisonTreatments이 필요합니다. 상위 항목은 해당 환경에 존재해야 합니다. update는 JSON Merge Patch입니다. parent 및 environment는 변경할 수 없습니다. delete는 영구 하드 삭제이며 destructive으로 분류됩니다. 생성/업데이트 시 선택적 owners: 각 항목은 {type: "USER", id or email} 또는 {type: "GROUP", identifier}입니다. 생성/업데이트 시 선택적 rule(타기팅 규칙 레이블 결과의 범위 지정 대상; 생략하면 생성 시 기본값은 "default", 업데이트 시 null는 이를 지움) 및 tags([{name}]; 업데이트는 목록을 대체하며 null/[]은 목록을 지움). list은 tags 배열 필터를 허용합니다(태그 이름 중 하나라도 포함된 실험). 항목에는 tags 및 rule이 포함됩니다.
fme_experiment_settings — 단일 실험의 통계 및 모니터링 설정(테스트 유형, 유의성 임계값, 다중 비교 보정, 최소 표본 크기, 검토 기간, 분산 감소). get/update/delete만 해당합니다. 실험과 1:1로 연결되며 list는 없습니다. get은 항상 적용된 설정(자체 재정의 또는 조직 기본값)을 반환하며 실험 자체가 존재하지 않는 경우를 제외하고 404를 반환하지 않습니다. update은 JSON Merge Patch이며 실험 수준 재정의를 암묵적으로 생성합니다. delete은 조직 기본값으로 되돌립니다(멱등적). 영구적이지 않지만 destructive로 분류됩니다.
fme_experiment_alerting — 단일 실험이 유의성 회귀 알림을 구독하는지 여부입니다. get/update만 해당합니다. 알림 정책이 없으면 get은 {id, isEnabled}를 반환하고 isEnabled: false를 보고합니다. 실험 자체가 존재하지 않는 경우에만 404를 반환합니다. update은 필수 isEnabled 불리언을 사용하는 JSON Merge Patch입니다.
fme_experiment_result — 실험의 최신 계산 실행에 대한 메트릭별 평가 결과입니다. list만 해당합니다(get은 없음 — 결과 자체에는 식별자가 없음). 모든 메트릭 범주에 걸쳐 (메트릭, 비교 처리) 쌍마다 한 행이 있습니다. 선택적 필터: metric_ids, comparisons. 최신 실행 결과만 반영하며 과거 데이터에는 접근할 수 없습니다.

단일 사용자/자체 호스팅 모드에서 레거시 모드 인증은 HARNESS_FME_API_KEY의 Bearer 토큰을 사용하며, 없으면 자리 표시자가 아닌 HARNESS_API_KEY로 대체합니다. HARNESS_FME_API_KEY는 레거시 Split 관리자 키 또는 FME 권한이 부여된 Harness PAT/SAT일 수 있지만, 공유 배포에서 각 세션 사용자의 자격 증명을 덮어쓸 수 없도록 multi-user 모드에서는 거부됩니다. Harness 플랫폼 API용 호스팅 OAuth/서비스 라우팅 자격 증명은 Split.io에 직접 요청할 때 인증에 사용되지 않습니다. fme_feature_flag은 레거시 모드에서 전체 수명 주기 관리를 지원합니다. 생성(traffic_type_id 필요), 목록, 가져오기, 메타데이터 업데이트, 삭제, 종료/복원/재할당/보관/보관 해제 실행 작업을 수행할 수 있습니다. fme_traffic_type를 사용해 트래픽 유형 ID를 확인하고, fme_identity을 사용해 ID 속성을 생성/업데이트하며, fme_standard_segment / fme_segment_keys를 사용해 표준 세그먼트를 확인하고 멤버 키를 추가하세요. fme_rule_based_segment은 타기팅 세그먼트의 CRUD를 제공하며, fme_rule_based_segment_definition는 활성화/비활성화 및 변경 요청 승인 흐름을 포함해 환경별 세그먼트 규칙을 관리합니다.

GitOps

리소스 유형	목록	가져오기	생성	업데이트	삭제	작업 실행
`gitops_agent`	x	x
`gitops_agent_metrics`	x
`gitops_argo_project`	x
`gitops_app_project_mapping`	x		x	x	x	`import`
`gitops_autocreate_log`	x
`gitops_application`	x	x				`sync`
`gitops_cluster`	x	x
`gitops_repository`	x	x
`gitops_applicationset`	x	x
`gitops_repo_credential`	x	x
`gitops_app_event`	x
`gitops_pod_log`		x
`gitops_managed_resource`	x
`gitops_resource_action`	x
`gitops_dashboard`		x
`gitops_app_resource_tree`		x
`gitops_cluster_link`	x		x		x

카오스 엔지니어링

리소스 유형	목록	가져오기	생성	업데이트	삭제	작업 실행
`chaos_experiment`	x	x	x	x	x	`run`, `stop`, `list_metadata`, `update_cron`
`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	x	x	`create_from_template`, `list_revisions`, `get_variables`, `get_yaml`, `compare_revisions`
`chaos_probe`	x	x	x		x	`list_metadata`, `enable`, `verify`, `get_manifest`
`chaos_probe_in_run`	x
`chaos_probe_template`	x	x	x	x	x	`get_variables`
`chaos_infrastructure`	x	x	x	x	x
`chaos_k8s_infrastructure`	x	x	x	x	x	`check_health`, `get_yaml`, `get_manifest`, `helm_command`
`chaos_enabled_infrastructure`	x
`chaos_environment`	x
`chaos_hub`	x	x	x	x	x	`list_metadata`
`chaos_hub_fault`	x
`chaos_fault`	x	x			x	`list_metadata`, `get_variables`, `get_yaml`
`chaos_fault_template`	x	x	x	x	x	`list_revisions`, `get_variables`, `get_yaml`, `compare_revisions`
`chaos_fault_experiment_run`	x
`chaos_action`	x	x	x	x	x	`list_metadata`, `get_manifest`
`chaos_action_template`	x	x	x	x	x	`list_revisions`, `get_variables`, `compare_revisions`
`chaos_loadtest`	x	x	x	x	x	`run`, `stop`, `estimate_workers`, `convert_har`
`chaos_loadtest_run`	x	x				`status`, `live_metrics`, `ai_insights`, `generate_ai_insights`
`chaos_service`	x	x	x	x	x	`list_experiment_runs`, `list_load_tests`
`custom_service`	x	x	x	x
`chaos_application_map`	x	x			x
`discovered_agent`	x
`discovered_namespace`	x
`discovered_service`	x
`discovered_network_map`	x
`chaos_guard_condition`	x	x	x	x	x
`chaos_guard_rule`	x	x	x	x	x	`enable`
`chaos_recommendation`	x	x
`chaos_onboarding`	x	x	x		x	`stats`, `confirm_discovery`, `onboard_services`, `confirm_service_onboarding`, `trigger_risk_scan`, `risk_scan`, `confirm_risk_scan`, `list_services`, `confirm_network_map`, `confirm_experiment_creation`, `confirm_experiment_run`, `skip`, `stop`
`chaos_pipeline_onboarding`	x	x	x		x	`can_onboard`
`chaos_risk`	x	x
`chaos_dr_test`	x		x
`scanned_risk`	x	x				`occurrences`, `summary_by_service`
`chaos_risk_rule`	x	x	x	x	x
`chaos_risk_scan`	x	x	x	x	x	`retry`, `abort`, `report`, `report_download`, `heatmap`, `submit_findings`
`chaos_dashboard`	x	x		x
`chaos_image_registry`		x	x	x		`resolve`

클라우드 비용 관리 (CCM)

리소스 유형	목록	가져오기	생성	업데이트	삭제	작업 실행
`cost_perspective`	x	x	x	x	x
`cost_breakdown`	x
`cost_timeseries`	x
`cost_summary`	x	x
`cost_recommendation`	x	x				`update_state`, `override_savings`, `create_jira_ticket`, `create_snow_ticket`
`cost_anomaly`	x
`cost_anomaly_summary`		x
`cost_category`	x	x
`cost_account_overview`		x
`cost_filter_value`	x
`cost_recommendation_stats`		x
`cost_recommendation_detail`		x
`cost_commitment`		x
`ai_budget`	x	x	x	x	x
`ai_budget_overview`		x
`ai_budget_consumption`	x
`ai_budget_override_request`	x	x	x			`approve`, `reject`

소프트웨어 엔지니어링 인사이트 (SEI)

SEI 리소스는 토큰 효율성을 위해 통합되어 있습니다. DORA, 팀/조직 트리 세부 정보 및 AI 인사이트에는 metric 또는 aspect 매개변수를 사용하세요.

리소스 유형	목록	가져오기	작업 실행
`sei_metric`	x
`sei_productivity_metric`		x
`sei_dora_metric`		x	`metric` 전달: deployment_frequency, change_failure_rate, mttr, lead_time 또는 *_drilldown
`sei_team`	x	x
`sei_team_detail`	x		`aspect` 전달: integrations, developers, integration_filters
`sei_org_tree`	x	x
`sei_org_tree_detail`	x	x	`aspect` 전달: efficiency_profile, productivity_profile, business_alignment_profile, integrations, teams
`sei_business_alignment`	x	x	`aspect` 전달: feature_metrics, feature_summary, get의 경우 drilldown
`sei_ai_usage`	x	x	`aspect` 전달: metrics, breakdown, summary, top_languages
`sei_ai_adoption`	x	x	`aspect` 전달: metrics, breakdown, summary
`sei_ai_impact`		x	`aspect` 전달: pr_velocity, rework
`sei_ai_raw_metric`	x

소프트웨어 공급망 보증(SCS)

리소스 유형	목록	가져오기
`scs_artifact_source`	x
`artifact_security`	x	x
`scs_artifact_component`	x
`scs_artifact_remediation`		x
`scs_chain_of_custody`		x
`scs_compliance_result`	x
`code_repo_security`	x	x
`scs_sbom`		x

Evidence Vault

Evidence Vault는 in-toto 증명(SDLC 증거)을 저장합니다. 목록 조회는 resource_scope를 통해 계정/조직/프로젝트 범위를 지원합니다. 단일 자유 텍스트 필터(pipeline, artifact 단독, gitoid)에는 search_term을 사용하고, 추가 Name 제약 조건에는 filters.subject_name를 사용하며, subject 콘텐츠 다이제스트에는 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" 및 Pending, Approved, Rejected, Expired 또는 Canceled와 같은 명시적 status과 함께 사용합니다.
harness_execute을 action="approve" 및 필수 body.scope과 함께 사용합니다: CURRENT, ACCOUNT, ORG 또는 PROJECT. CURRENT은 예외의 기존 범위에서 승인하며, 다른 범위는 내부적으로 STO 승격 엔드포인트를 사용합니다. 생략된 경우 서버는 인증된 사용자로부터 body.approver_id를 자동으로 채웁니다. body.comment는 선택 사항입니다.
예외를 거부하려면 action="reject"을 사용합니다. 생략된 경우 body.approver_id도 자동으로 채워집니다.
별도의 promote 실행 작업은 없습니다. 요청된 결과가 계정, 조직 또는 프로젝트 범위에서의 승인인 경우, action="approve"를 CURRENT이 아닌 body.scope과 함께 사용합니다.

액세스 제어

리소스 유형	목록	가져오기	생성	업데이트	삭제
`user`	x	x
`user_group`	x	x	x	x	x
`service_account`	x	x	x		x
`role`	x	x	x		x
`role_assignment`	x		x
`resource_group`	x	x	x		x
`permission`	x

거버넌스

리소스 유형	목록	가져오기	생성	업데이트	삭제
`policy`	x	x	x	x	x
`policy_set`	x	x	x	x	x
`policy_evaluation`	x	x

배포 동결

리소스 유형	목록	가져오기	생성	업데이트	삭제	작업 실행
`freeze_window`	x	x	x	x	x	`toggle_status`
`global_freeze`		x				`manage`

서비스 재정의

리소스 유형	목록	가져오기	생성	업데이트	삭제	작업 실행
`service_override`	x	x	x	x	x

설정

리소스 유형	목록	가져오기	생성	업데이트	삭제	작업 실행
`setting`	x

MCP 프롬프트

DevOps

프롬프트	설명	매개변수
`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을 입력받습니다. 단계/스텝별 분석, 실패 세부 정보, delegate 정보 및 실패한 스텝 로그를 `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`	delegate 연결 상태, 상태 정보, 토큰 상태를 확인하고 인프라 문제 해결을 지원합니다.	`projectId` (선택 사항)
`developer-portal-scorecard`	서비스의 IDP 스코어카드를 검토하고 개발자 경험 개선을 위한 격차를 파악합니다.	`projectId` (선택 사항)
`pending-approvals`	승인을 기다리는 파이프라인 실행을 찾아 세부 정보를 표시하고 승인 또는 거부를 제안합니다.	`projectId` (선택 사항), `orgId` (선택 사항), `pipelineId` (선택 사항)

FinOps

프롬프트	설명	매개변수
`optimize-costs`	클라우드 비용 데이터를 분석하고 잠재적 절감액을 기준으로 우선순위를 정해 권장 사항과 이상 징후를 제시합니다.	`projectId` (선택 사항)
`cloud-cost-breakdown`	추세 분석 및 이상 징후 탐지를 통해 서비스, 환경 또는 클러스터별 클라우드 비용을 심층 분석합니다.	`perspectiveId` (선택 사항), `projectId` (선택 사항)
`commitment-utilization-review`	예약 인스턴스 및 절감형 플랜의 사용률을 분석해 낭비를 파악하고 약정 사용을 최적화합니다.	`projectId` (선택 사항)
`cost-anomaly-investigation`	비용 이상 징후를 조사해 근본 원인, 영향을 받은 리소스 및 해결 방법을 파악합니다.	`projectId` (선택 사항)
`rightsizing-recommendations`	적정 규모 조정 권장 사항을 검토하고 우선순위를 정하며, 필요에 따라 Jira 또는 ServiceNow 티켓을 생성합니다.	`projectId` (선택 사항), `minSavings` (선택 사항)

DevSecOps

프롬프트	설명	매개변수
`security-review`	Harness 리소스 전반의 보안 문제를 검토하고 심각도별 해결 방법을 제안합니다.	`projectId` (선택 사항), `severity` (선택 사항, 기본값: `critical,high`)
`vulnerability-triage`	파이프라인과 아티팩트 전반의 보안 취약점을 분류하고 심각도와 악용 가능성을 기준으로 우선순위를 정합니다.	`projectId` (선택 사항), `severity` (선택 사항)
`sbom-compliance-check`	아티팩트의 SBOM 및 규정 준수 상태를 감사해 라이선스 위험, 정책 위반, 구성 요소 취약점을 파악합니다.	`artifactId` (선택 사항), `projectId` (선택 사항)
`supply-chain-audit`	엔드투엔드 소프트웨어 공급망 보안 감사를 수행합니다. 출처, 관리 연속성 및 정책 준수 여부를 확인합니다.	`projectId` (선택 사항)
`security-exemption-review`	보류 중인 보안 예외를 검토하고 일괄 승인 또는 거부를 결정합니다.	`projectId` (선택 사항)
`bulk-exemption-create`	명시적인 범위 및 기간 지침을 포함해 여러 STO 문제에 대해 타당한 보안 예외를 생성합니다.	`projectId` (필수), `exemption_type` (필수), `reason` (필수), 문제 필터 (선택 사항)
`access-control-audit`	최소 권한 원칙을 적용하기 위해 사용자 권한, 과도한 권한이 부여된 계정 및 역할 할당을 감사합니다.	`projectId` (선택 사항), `orgId` (선택 사항)

Harness Code

프롬프트	설명	매개변수
`code-review`	풀 리퀘스트 검토 — diff, 커밋, 검사 및 댓글을 분석하여 버그, 보안, 성능 및 스타일에 대한 구조화된 피드백 제공	`repoId` (필수), `prNumber` (필수), `projectId` (선택 사항)
`pr-summary`	브랜치의 커밋 기록과 diff를 바탕으로 PR 제목과 설명 자동 생성	`repoId` (필수), `sourceBranch` (필수), `targetBranch` (선택 사항, 기본값: main), `projectId` (선택 사항)
`branch-cleanup`	저장소의 브랜치를 분석하고 오래되었거나 병합된 브랜치의 삭제 권장	`repoId` (필수), `projectId` (선택 사항)

MCP 리소스

리소스 URI	설명	MIME 유형
`pipeline:///{pipelineId}`	파이프라인 YAML 정의	`application/x-yaml`
`pipeline:///{orgId}/{projectId}/{pipelineId}`	명시적 범위가 포함된 파이프라인 YAML	`application/x-yaml`
`executions:///recent`	최근 파이프라인 실행 요약 10개	`application/json`
`schema:///pipeline`	Harness 파이프라인 JSON 스키마	`application/schema+json`
`schema:///template`	Harness 템플릿 JSON 스키마	`application/schema+json`
`schema:///trigger`	Harness 트리거 JSON 스키마	`application/schema+json`
`schema:///pipeline_v1` (알파)	Harness V1 파이프라인 JSON 스키마 (간소화된 stages/steps 형식)	`application/schema+json`
`schema:///agent-pipeline`	Harness AI 에이전트 파이프라인 JSON 스키마	`application/schema+json`
`agent-docs:///legacy-format`	레거시 에이전트 사양 형식 참조(`agent.step.group.steps` / `PLUGIN_TASK`). 기존 레거시 형식 에이전트를 업데이트할 때 `create-agent` 프롬프트에서 읽음	`text/markdown`

도구 세트 필터링

기본적으로 50개 도구 세트 중 44개가 활성화됩니다. 5개 도구 세트는 선택적으로 활성화할 수 있으며 기본값에서 제외됩니다.

ansible — Harness Ansible(인벤토리, 플레이북, 호스트, 활동). 프로젝트 범위이며 많은 사용자가 필요로 하지 않는 개념을 추가하므로 선택적으로 활성화됩니다.
appsec — Traceable 애플리케이션 및 API 보안(API 인벤토리, OpenAPI 사양, 샘플 스팬, 민감한 데이터 유형, 런타임 위협 활동, 보안 이벤트, AST 스캔 및 인벤토리 추세). 전용 HARNESS_APPSEC_API_KEY가 필요하고 api.traceable.ai을 대상으로 하므로 선택적으로 활성화됩니다.
autonomous_work — Development Harness(자율 작업). 선택적으로 활성화됩니다. 범위는 도구 세트 설명을 참조하세요.
observability-evaluations — 예약된 프로덕션 텔레메트리 평가 규칙. 배포된 점수 산정 컨트롤 플레인에 의존하므로 선택적으로 활성화됩니다.
unified-search — 검색 서비스가 제공하는 모든 소스에 대한 시맨틱 검색. 백엔드가 모든 클러스터에 배포되어 있지 않고 계정별로 기능 플래그가 설정되므로 선택적으로 활성화됩니다(통합 검색 참조).
registries-v3 — Harness Artifact Registry v3(패키지, 버전, 파일, 메타데이터, 스캔, 방화벽 예외). v3 쓰기 기능이 제공될 때까지 선택적으로 활성화되므로 에이전트가 v1 레지스트리/아티팩트와 v3 패키지/버전을 구분할 필요가 없습니다.

`+` 접두사를 사용해 도구 세트 추가

+ 접두사를 사용하면 모든 기본 도구 세트와 함께 선택적 도구 세트를 명시적으로 포함할 수 있습니다.

# Explicitly include Ansible alongside all defaults
HARNESS_TOOLSETS=+ansible

기본 도구 세트 제거

필요하지 않은 도구 세트를 제외하려면 - 접두사를 사용하세요.

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

+와 - 조합

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

명시적 허용 목록

명시적인 쉼표로 구분된 목록(접두사 없음)을 지정하면 기본값이 완전히 대체됩니다. 목록에 있는 도구 세트만 활성화됩니다.

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

사용 가능한 도구 세트 이름:

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

아키텍처

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

작동 방식

도구는 일반적인 동사입니다: harness_list, harness_get 등입니다. 올바른 API 엔드포인트로 라우팅하는 resource_type 매개변수를 받습니다.
레지스트리는 각 resource_type을 HTTP 메서드, URL 경로, 경로/쿼리 매개변수 매핑, 응답 추출 로직을 지정하는 선언적 데이터 구조인 ResourceDefinition에 매핑합니다.
디스패치는 리소스 정의를 확인하고, HTTP 요청을 구성한 다음(경로 대체, 쿼리 매개변수, resource_scope을 고려한 계정/조직/프로젝트 주입), HarnessClient을 통해 Harness API를 호출하고 관련 응답 데이터를 추출합니다.
도구 세트 필터링(HARNESS_TOOLSETS)은 시작 시 레지스트리에 로드할 리소스 정의를 제어합니다.
구조화된 출력은 MCP outputSchema으로 선언합니다. harness_list는 배열과 일반적인 목록 래퍼를 엄격한 클라이언트를 위한 객체 형태의 structuredContent으로 변환합니다.
딥 링크가 응답에 자동으로 추가되어 모든 리소스에 대한 Harness UI 직접 URL을 제공합니다.
간결 모드는 목록 결과에서 장황한 메타데이터를 제거하고, 토큰 사용량을 최소화하기 위해 실행 가능한 필드(식별 정보, 상태, 유형, 타임스탬프, 딥 링크)만 유지합니다.

새 리소스 유형 추가

src/registry/toolsets/에 새 파일을 만들거나 기존 도구 세트에 리소스를 추가합니다.

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

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

그런 다음 src/registry/index.ts에서 가져와 ALL_TOOLSETS 배열에 추가합니다. 도구 파일은 변경할 필요가 없습니다.

개발

# Build
pnpm build

# Watch mode
pnpm dev

# Type check
pnpm typecheck

# Run tests
pnpm test

# Watch tests
pnpm test:watch

# Interactive MCP Inspector
pnpm inspect

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

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

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

프로젝트 구조

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

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

사용자 확인 요청

쓰기 도구(harness_create, harness_update, harness_delete, harness_execute)는 작업의 위험도에 따라 확인이 필요한 경우 MCP 사용자 확인 요청을 사용해 사용자에게 확인을 요청합니다. medium_write, high_write, destructive 작업에만 해당합니다. 위험도가 낮은 생성/업데이트/읽기 작업(예: pipeline.create, pipeline.update, hql_query.run)은 확인 요청 없이 조용히 진행됩니다. 확인 요청이 표시되면 사용자는 실행될 작업을 확인하고 수락하거나 거부할 수 있으므로, 실제로 데이터를 변경하거나 작업을 실행하는 작업에 대해 사람이 직접 승인할 수 있습니다.

작동 방식:

LLM이 medium_write 이상의 위험도를 가진 쓰기 도구를 호출합니다(예: harness_delete, harness_execute pipeline.run). 위험도가 낮은 생성/업데이트/읽기 작업은 확인 요청을 표시하지 않습니다.
서버는 작업 요약과 기본적으로 선택된 confirm 확인란을 포함한 사용자 확인 요청을 클라이언트에 보냅니다.
사용자는 세부 정보를 확인하고 confirm이 선택된 상태로 수락하거나 거부 / 취소를 클릭합니다.
confirm: true가 선택된 상태로 수락하면 작업이 진행됩니다. confirm이 선택되지 않은 상태로 수락하거나, 거부하거나, 취소하면 작업이 차단되고 LLM에 알립니다(명시적인 거부는 최종 결정이며 도구 호출의 confirm: true로 우회할 수 없습니다).

클라이언트 지원:

클라이언트	사용자 확인 요청 지원
Cursor	예
VS Code (Copilot)	예
Claude Desktop	아직 지원 안 함
Devin Desktop	아직 지원 안 함
MCP Inspector	예

클라이언트 지원이 없는 경우 사용자 확인 요청 동작은 작업 위험도에 따라 달라집니다.

위험 수준	클라이언트의 사용자 확인 요청 지원 여부	`confirm: true` 전달 여부	동작
`read`, `low_write`	모두 해당	모두 해당	확인 요청 없이 조용히 진행 — 이 위험 수준에서는 확인 요청이 표시되지 않으며 `confirm`은 아무런 영향을 주지 않습니다
`medium_write`, `high_write`, `destructive`	예	모두 해당	사용자에게 확인을 요청합니다. 사용자가 `confirm: true`(스키마의 기본값)을 선택한 상태로 수락한 경우에만 진행합니다. 명시적인 거부, 취소 또는 `confirm: false`이 선택되지 않은 상태로 수락한 경우(사용자가 확인란 선택을 해제함)는 최종 결정이며 도구 호출의 `confirm: true`로 우회할 수 없습니다. `confirm` 필드 없이 수락하면 클라이언트가 사용 가능한 확인 요청을 표시하지 못한 것으로 간주하며, `confirm: true`으로 재시도해 복구할 수 있습니다
`medium_write`, `high_write`, `destructive`	아니요	아니요	차단(`confirm: true`으로 재시도하라는 안내와 함께 오류 반환)
`medium_write`, `high_write`, `destructive`	아니요	예	진행(비대화형 자동화를 위한 명시적 동의)
모든 위험 수준(`HARNESS_AUTO_APPROVE_RISK` 이하)	모두 해당	모두 해당	확인 요청 없이 자동 승인

medium_write 이상의 작업에서 런타임에 elicitInput이 실패하면(전송 오류, 지원되지 않는 메서드) 호출자가 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에 로그를 기록하지 않습니다. stdio JSON-RPC 전송이 손상되지 않도록 모든 로그는 stderr로 출력됩니다.

함께 사용하면 좋은 스킬

Harness MCP 서버는 일반적인 Harness 워크플로를 위해 준비된 Claude Code 스킬(슬래시 명령) 모음인 **Harness Skills**과 함께 사용하면 좋습니다. 이 MCP 서버와 함께 설치하면 사용자 지정 프롬프트를 작성하지 않고도 /deploy, /rollback, /triage 등의 고수준 자동화를 사용할 수 있습니다.

문제 해결 및 일반적인 주의 사항

증상	가능한 원인	조치
`HARNESS_ACCOUNT_ID is required when the API key does not include an account ID segment...`	API 키가 지원되는 계정 범위 형식(`pat.<accountId>...` 또는 `sat.<accountId>...`)이 아니어서 계정 ID를 추론할 수 없음	`HARNESS_ACCOUNT_ID`을 명시적으로 설정
시작 시 `Unknown transport: "..."`	지원되지 않는 CLI 전송 인수	`stdio` 또는 `http`만 사용
시작 시 `Invalid HARNESS_TOOLSETS: ...`	하나 이상의 도구 세트 이름을 인식할 수 없음	도구 세트 필터링에 있는 이름만 사용(정확히 일치해야 함)
HTTP `mcp-session-id header is required...`	세션 헤더 없이 세션 요청이 전송됨	먼저 `initialize`를 전송한 다음 `POST/GET/DELETE /mcp`에 `mcp-session-id`을 포함
HTTP `Session not found...`	`MCP_SESSION_TTL_MS`밀리초 동안 유휴 상태였거나 이미 닫혀 세션이 만료됨	`initialize`을 다시 실행해 새 세션을 만든 다음 새 헤더로 재시도
`/mcp`의 HTTP `405 Method Not Allowed`	MCP 엔드포인트에서 지원되지 않는 메서드	`POST`, `GET`, `DELETE` 또는 `OPTIONS`만 사용
HTTP `Invalid request`	JSON 본문이 잘못되었거나 요청 본문이 `HARNESS_MAX_BODY_SIZE_MB`를 초과함	JSON 페이로드의 크기와 형식을 확인하고, 필요한 경우 `HARNESS_MAX_BODY_SIZE_MB`을 늘리세요
도구에서 `Unknown resource_type "..."`	리소스 유형의 철자가 틀렸거나 `HARNESS_TOOLSETS`을 통해 필터링됨	`harness_describe`를 호출해 유효한 유형을 확인하세요(선택적으로 `search_term` 사용)
`Missing required field "... for path parameter ..."`	프로젝트/조직 범위 호출에 식별자가 누락됨	`HARNESS_ORG`/`HARNESS_PROJECT`을 설정하거나 도구 호출마다 `org_id`/`project_id`를 전달하세요
`resource_scope "org" requires org_id...` 또는 `resource_scope "project" requires project_id...`	다중 범위 리소스가 식별자 부족 상태에서 조직/프로젝트 범위로 강제 지정됨	누락된 `org_id`/`project_id`를 전달하거나, `HARNESS_ORG`/`HARNESS_PROJECT`을 구성하거나, 지원되는 경우 `resource_scope: "account"`를 사용하세요
`Read-only mode is enabled ... operations are not allowed`	`HARNESS_READ_ONLY=true`가 생성/업데이트/삭제/실행을 차단함	쓰기 작업이 필요한 경우 `HARNESS_READ_ONLY=false`를 설정하세요
파이프라인 실행이 사전 검사에서 필수 입력을 확인하지 못해 실패함	제공된 `inputs`이 필수 런타임 자리표시자를 모두 포함하지 않음	`runtime_input_template`을 가져와 누락된 단순 키를 제공하거나, 구조화된 입력에는 `input_set_ids`을 사용하세요
파이프라인 CI 축약 표기(`branch`, `tag`, `pr_number`, `commit_sha`)가 적용되지 않음	`inputs.build`이 이미 제공되어 축약 표기 확장이 의도적으로 생략됨	축약 표기 확장을 사용하려면 `inputs.build`를 제거하거나, 전체 명시적 `build` 구조를 유지하세요
파이프라인 실행에서 잘못된 YAML 리비전이 로드됨	파이프라인 정의가 Git에 저장되어 있으며 실행 시 원하는 파이프라인 브랜치를 지정하지 않음	`run` 작업에서 `params.pipeline_branch`을 전달하세요. 이는 Harness `branch`에 매핑됩니다
`wait: true`에서 `_wait.error`을 반환함	파이프라인 트리거는 성공했지만 서버 측 폴링이 실패함	재실행 여부를 결정하기 전에 `harness_get(resource_type="execution", ...)`로 `execution_id`을 다시 확인하세요
`wait: true`에서 `execution_timed_out: true`를 반환함	`wait_timeout_seconds` 전에 실행이 종료 상태에 도달하지 못함	반환된 `execution_id`을 사용해 상태를 다시 확인하고, `harness_diagnose`을 실행하기 전에 종료 상태가 될 때까지 기다리세요
실행 로그가 비어 있거나 블롭 다운로드에서 403이 반환됨	Harness 호스팅 로그 블롭 URL에는 구성된 Harness 클라이언트/인증 경로가 필요하며, 특히 내부 또는 자체 관리 호스트에서 필요함	`HARNESS_BASE_URL`이 대상 Harness 호스트를 가리키도록 유지하고, MCP 클라이언트를 우회하는 대신 `harness_get(resource_type="execution_log", ...)` 또는 `harness_diagnose(..., include_logs=true)`을 사용하세요
`Operation declined by user` / `Operation cancelled by user`	사용자가 확인 대화상자를 거부하거나 취소함 — 최종 결정 권한은 사용자에게 있음	사용자와 작업 세부 정보를 확인하세요. `confirm: true`은 명시적인 거부를 우회하지 않습니다. 사용자가 프롬프트를 수락해야 합니다
`Operation blocked: the client could not surface a usable confirmation prompt`	클라이언트가 elicitation을 지원하지 않거나, `elicitInput`가 실패했거나, 퇴화된 수락을 반환함	비대화형 자동화에는 `confirm: true`으로 재시도하거나 elicitation을 지원하는 클라이언트를 사용하세요
템플릿 생성/업데이트 시 `body.template_yaml (or body.yaml) is required`	템플릿 API에는 전체 YAML 페이로드가 필요함	`body`에 전체 `template_yaml` 문자열을 제공하세요. 삭제하려면 `version_label`을 전달해 버전 하나를 삭제하세요(생략하면 모든 버전 삭제)
시작 시 `HARNESS_BASE_URL must use HTTPS`	`HARNESS_BASE_URL`가 HTTP URL로 설정됨	HTTPS를 사용하거나 로컬 개발을 위해 `HARNESS_ALLOW_HTTP=true`을 설정하세요

라이선스

MIT

Harness

Harness MCP(으)로 무엇을 할 수 있나요?

문서

Harness MCP Server 2.0

이 MCP 서버를 사용하는 이유

사전 요구 사항

빠른 시작

옵션 0: 호스팅 Harness MCP

옵션 1: npx(권장)

옵션 2: 전역 설치

옵션 3: 소스에서 빌드

Anthropic MCP Directory 번들

CLI 사용법

HTTP 전송

HarnessID OAuth 모드

업스트림 ID 공급자 OAuth 프록시 모드

다중 사용자 모드

클라이언트 구성

호스팅 Harness MCP

Claude Desktop (claude_desktop_config.json)

Claude Code (via claude mcp add)

Cursor (.cursor/mcp.json)

Devin Desktop (~/.windsurf/mcp.json)

MCP 게이트웨이

Docker MCP Gateway

Portkey

LiteLLM

Envoy AI Gateway

Kong

기타 게이트웨이

Docker

Kubernetes

구성

시맨틱 검색

HTTPS 적용

감사 로깅

도구 참조

스키마 조회 워크플로

도구 예시

파이프라인 실행 워크플로(권장)

동적 파이프라인 실행

실행 입력 포렌식

파이프라인 실행 대기 모드

파이프라인 저장 모드

리소스 유형

플랫폼

파이프라인

AI 에이전트

서비스

환경

커넥터

인프라

시크릿

실행 로그

감사 추적

Delegate

코드 저장소

아티팩트 레지스트리

파일 저장소

템플릿

대시보드

Database DevOps

Infrastructure as Code Management (IaCM)

Internal Developer Portal (IDP)

풀 리퀘스트

릴리스 관리

통합 검색

Vibe

기능 플래그

GitOps

카오스 엔지니어링

클라우드 비용 관리 (CCM)

소프트웨어 엔지니어링 인사이트 (SEI)

소프트웨어 공급망 보증(SCS)

Evidence Vault

보안 테스트 오케스트레이션(STO)

액세스 제어

거버넌스

배포 동결

서비스 재정의

Claude Desktop (`claude_desktop_config.json`)

Claude Code (via `claude mcp add`)

Cursor (`.cursor/mcp.json`)

Devin Desktop (`~/.windsurf/mcp.json`)

`+` 접두사를 사용해 도구 세트 추가