Harness

Servidor MCP Harness 2.0

Um servidor MCP (Model Context Protocol) que dá aos agentes de IA acesso completo à plataforma Harness.io por meio de 11 ferramentas consolidadas e 224 tipos de recursos.

Por que usar este servidor MCP

A maioria dos servidores MCP mapeia uma ferramenta por endpoint de API. Para uma plataforma tão ampla quanto a Harness, isso significa mais de 240 ferramentas — e os LLMs pioram na seleção de ferramentas conforme a contagem cresce. As janelas de contexto ficam cheias de esquemas, e cada novo endpoint significa código novo.

Este servidor foi construído de forma diferente:

• 11 ferramentas, 224 tipos de recursos. Um sistema de despacho baseado em registro roteia harness_list, harness_get, harness_create, etc. para qualquer recurso da Harness — pipelines, serviços, ambientes, organizações, projetos, feature flags, dados de custo e muito mais. O LLM escolhe entre 11 ferramentas em vez de centenas.
• Cobertura completa da plataforma. 38 conjuntos de ferramentas padrão abrangendo CI/CD, GitOps, Feature Flags, Cloud Cost Management, Security Testing, Chaos Engineering, Database DevOps, Internal Developer Portal, Software Supply Chain, Infrastructure as Code Management, Governance, Service Overrides, Knowledge Graph e mais. Cobertura opcional de Ansible está disponível quando você precisa de dados de inventário e playbooks.
• Fluxos de trabalho multi-projeto prontos para uso. Os agentes descobrem organizações e projetos dinamicamente — sem necessidade de variáveis de ambiente fixas. Pergunte "mostre execuções com falha em todos os projetos" e o agente pode navegar por toda a hierarquia da conta.
• 34 modelos de prompt. Prompts pré-construídos para fluxos de trabalho comuns: criar e implantar aplicativos de ponta a ponta, depurar pipelines com falha, revisar métricas DORA, triar vulnerabilidades, otimizar custos de nuvem, auditar controle de acesso, planejar lançamentos de feature flags, revisar pull requests, aprovar pipelines pendentes e mais.
• Funciona em qualquer lugar. Transporte Stdio para clientes locais (Claude Desktop, Cursor, Devin Desktop), transporte HTTP para implantações remotas/compartilhadas, pronto para Docker e Kubernetes.
• Início sem configuração. Basta fornecer uma chave de API da Harness. O ID da conta é extraído automaticamente de tokens PAT e SAT, os padrões de organização/projeto são opcionais, e a filtragem de conjuntos de ferramentas permite expor apenas o que você precisa.
• Extensível por design. Adicionar um novo recurso da Harness significa adicionar um arquivo de dados declarativo — sem registro de nova ferramenta, sem alterações de esquema, sem atualizações de prompt.

Pré-requisitos

Antes de instalar ou executar o servidor, você precisa de uma chave de API da Harness:

1. Faça login na sua conta Harness
2. Vá para Meu Perfil → Chaves de API → + Nova Chave de API
3. Crie um novo Token sob a chave de API — isso gera um PAT ou SAT no formato <prefix>.<accountId>.<tokenId>.<secret>
4. Salve o token em um local seguro — você vai precisar dele na próxima etapa

Para instruções detalhadas, consulte o Quickstart da API Harness.

Início Rápido

Opção 0: Harness MCP Hospedado

Se a sua conta Harness tiver o serviço MCP hospedado habilitado, clientes que suportam servidores MCP remotos podem se conectar diretamente ao endpoint gerenciado em vez de executar o servidor localmente.

Importante: O serviço MCP hospedado usa OAuth da Plataforma Harness, não HARNESS_API_KEY. Ele também deve ser habilitado/configurado por conta pelo Suporte da Harness antes que o endpoint possa ser usado.

Consulte Harness MCP Hospedado para exemplos de configuração.

Opção 1: npx (Recomendado)

Nenhuma instalação necessária — basta executar:

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

Ou configure a chave de API no seu cliente de IA (consulte Configuração do Cliente abaixo).

# 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

Observação: O ID da conta é extraído automaticamente de tokens PAT e SAT (pat.<accountId>... ou sat.<accountId>...), portanto HARNESS_ACCOUNT_ID só é necessário para chaves de API sem um segmento de conta incorporado.

Opção 2: Instalação Global

npm install -g harness-mcp-v2

# Then run directly
harness-mcp-v2

Opção 3: Compilar a partir do Código-Fonte

Para desenvolvimento ou personalização:

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

Pacote do Diretório MCP da Anthropic

O manifesto do pacote MCPB fica em [mcp-directory/](mcp-directory/), e o ícone do pacote é rastreado em [icon.png](icon.png) na raiz do repositório. Copie mcp-directory/manifest.json para a raiz do pacote após pnpm build para que o arquivo gerado contenha manifest.json, icon.png, build/, package.json e node_modules/ de produção no nível raiz.

Para manter o arquivo pequeno, compile pacotes MCPB a partir de um diretório de preparação:

pnpm prepare:mcpb

O pacote preparado é gravado em dist/mcpb/ com dependências de produção instaladas usando o layout plano do npm.

Uso via 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

O transporte padrão é stdio se não for especificado. Use http para implantações remotas/compartilhadas.

Transporte HTTP

Ao executar em modo HTTP, o servidor expõe:

Endpoint	Método	Descrição
/mcp	POST	Endpoint JSON-RPC MCP (initialize + solicitações de sessão)
/mcp	GET	Fluxo SSE para mensagens iniciadas pelo servidor (progresso, elicitação)
/mcp	DELETE	Encerra uma sessão MCP ativa
/mcp	OPTIONS	Preflight CORS
/health	GET	Verificação de saúde — retorna { "status": "ok", "sessions": <count> }

O transporte HTTP opera em modo baseado em sessão. Uma nova sessão MCP é criada em initialize, o servidor retorna um cabeçalho mcp-session-id, e solicitações subsequentes para essa sessão devem incluir o mesmo cabeçalho.

Restrições operacionais no modo HTTP:

• Defina HARNESS_MCP_AUTH_TOKEN para qualquer implantação compartilhada ou remotamente acessível. Quando definido, toda solicitação POST, GET e DELETE para /mcp deve incluir Authorization: Bearer <token>.
• Ligações não-loopback exigem HARNESS_MCP_AUTH_TOKEN por padrão. Para executar sem autenticação em uma interface não-loopback mesmo assim, defina HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP=true explicitamente.
• POST /mcp sem mcp-session-id deve ser uma solicitação initialize.
• POST /mcp, GET /mcp e DELETE /mcp para sessões existentes exigem o cabeçalho mcp-session-id.
• GET /mcp é usado para notificações SSE (atualizações de progresso e prompts de elicitação).
• Sessões ociosas são encerradas após MCP_SESSION_TTL_MS milissegundos quando nenhuma solicitação ou fluxo SSE está ativo (padrão 1800000, ou 30 minutos).
• GET /health é o único endpoint não-MCP.
• O tamanho do corpo da solicitação é limitado por HARNESS_MAX_BODY_SIZE_MB (padrão 10 MB).
• Defina x-harness-pipeline-version: 0 ou 1 na solicitação initialize para selecionar recursos de pipeline V0 ou V1 para essa sessão HTTP.
• Defina x-harness-auto-approve-risk: none|low_write|medium_write|high_write|all na solicitação initialize para escolher um limite de aprovação automática por sessão mais rigoroso. O servidor limita esse valor ao HARNESS_AUTO_APPROVE_RISK do nível de implantação, então uma sessão pode reduzir, mas não expandir, o teto de aprovação configurado.

Modo Multi-Usuário

Defina HARNESS_MCP_MODE=multi-user para implantações HTTP compartilhadas onde cada cliente se autentica como um usuário Harness diferente. Neste modo:

• HARNESS_API_KEY não deve estar definido na configuração do servidor — o servidor não mantém credenciais da Harness.
• Cada sessão deve fornecer x-harness-api-key na solicitação initialize. x-harness-account-id é obrigatório apenas quando a chave de API não incorpora um segmento de conta.
• As sessões também podem fornecer cabeçalhos x-harness-org e x-harness-project para definir o escopo padrão para essa sessão.
• A chave de API da Harness flui para cada chamada de API da Harness daquela sessão, então a trilha de auditoria na Harness reflete o usuário real.
• HARNESS_MCP_AUTH_TOKEN é independente e ainda pode ser usado como um controle adicional na camada de transporte.

# 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 controla a validação do cabeçalho Host para proteção contra rebinding de DNS, e o CORS limita origens de navegador. Nenhum dos dois é autenticação; use HARNESS_MCP_AUTH_TOKEN ou um gateway/proxy reverso autenticado para controle de acesso.

Configuração do Cliente

Observação: HARNESS_ORG e HARNESS_PROJECT são opcionais. Eles definem o ID da organização e o ID do projeto usados quando não são especificados por chamada de ferramenta. Os agentes podem descobrir organizações e projetos dinamicamente usando harness_list(resource_type="organization") e harness_list(resource_type="project"). Os nomes descontinuados HARNESS_DEFAULT_ORG_ID e HARNESS_DEFAULT_PROJECT_ID ainda são aceitos para compatibilidade com versões anteriores.

Harness MCP Hospedado

A Harness também suporta um endpoint MCP hospedado para contas que têm o serviço gerenciado habilitado. Isso é útil quando você quer um endpoint MCP remoto compartilhado em vez de executar npx harness-mcp-v2 ou auto-hospedar o transporte HTTP você mesmo.

Importante: A autenticação MCP hospedada usa OAuth da Plataforma Harness. Ela não usa HARNESS_API_KEY na configuração do cliente. A disponibilidade do MCP hospedado é configurada por conta Harness, então você precisará trabalhar com o Suporte da Harness para habilitar/configurar a configuração antes de usá-la.

O endpoint hospedado https://mcp.harness.io/mcp é um serviço gerenciado. A configuração MCP do lado do cliente no Claude, Cursor ou Cowork não pode substituir para qual ambiente Harness ele roteia. Para Harness0 ou outro ambiente SaaS privado da Harness, peça ao Suporte da Harness para habilitar/configurar o MCP hospedado para esse ambiente, ou execute o servidor local/auto-hospedado e defina HARNESS_BASE_URL para o host Harness de destino.

Exemplo de MCP hospedado:

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

Exemplo com entradas hospedadas e locais:

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

Solução de problemas de npx ENOENT ou node: No such file or directory

Isso é uma falha de inicialização de processo do cliente, não uma falha de autenticação da Harness. O servidor MCP ainda não foi iniciado, então alterar HARNESS_API_KEY não afetará spawn npx ENOENT.

Aplicativos GUI (Cursor, Claude Desktop, Devin Desktop, VS Code) nem sempre herdam o PATH do seu shell, então eles podem não encontrar npx ou node após um recarregamento de configuração. Corrija isso usando caminhos absolutos e definindo explicitamente PATH no bloco env:

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

Encontre seus caminhos com which npx e which node em um terminal e, em seguida, certifique-se de que o diretório que contém node esteja incluído no valor PATH acima. Locais comuns:

• Homebrew (macOS): /opt/homebrew/bin/npx
• nvm: ~/.nvm/versions/node/v20.x.x/bin/npx (execute nvm which current para encontrar o caminho exato)
• Node do sistema: /usr/local/bin/npx

Claude Desktop (claude_desktop_config.json)

npx (sem instalação)

{
  "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 (instalação local)

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 (sem instalação)

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

node (instalação local)

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

Em seguida, defina HARNESS_API_KEY no seu ambiente ou no arquivo .env.

Cursor (.cursor/mcp.json)

npx (sem instalação, recomendado para configurações Cursor locais)

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

Execute which npx em um terminal e use esse caminho completo para command; inclua o diretório de which node no início de PATH.

node (instalação local)

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

Execute which harness-mcp-v2 após npm install -g harness-mcp-v2 e use esse caminho completo para command; inclua o diretório de which node no início de PATH.

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

npx (sem instalação)

{
  "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 (instalação local)

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

Usando uma compilação local a partir do código-fonte?

Substitua o comando pelo caminho para o seu index.js compilado:

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

Gateway MCP

O servidor MCP Harness é totalmente compatível com MCP Gateways — proxies reversos que fornecem autenticação centralizada, governança, roteamento de ferramentas e observabilidade em vários servidores MCP. Como o servidor implementa o protocolo MCP padrão com transportes stdio e HTTP, ele funciona atrás de qualquer gateway compatível com MCP sem alterações de código.

Por que usar um gateway?

• Gerenciamento centralizado de credenciais — sem chaves de API nas configurações de agentes
• Governança e registro de auditoria para todas as chamadas de ferramentas entre equipes
• Um único endpoint para agentes em vez de N conexões para N servidores MCP
• Controle de acesso — restrinja quais equipes podem usar quais ferramentas

Docker MCP Gateway

Registre o servidor na sua configuração do Docker MCP Gateway:

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

Portkey

Adicione o servidor MCP Harness ao seu Portkey MCP Gateway para governança empresarial, rastreamento de custos e roteamento multi-LLM:

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

LiteLLM

Adicione à sua configuração de proxy LiteLLM:

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

Envoy AI Gateway

O servidor funciona com o suporte MCP do Envoy AI Gateway via transporte HTTP:

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

Em seguida, configure o Envoy para rotear para http://localhost:8080/mcp como um backend MCP upstream.

Kong

Use o plugin AI MCP Proxy do Kong para expor o servidor MCP Harness por meio da sua infraestrutura de gateway Kong existente.

Outros Gateways

Qualquer gateway que suporte a especificação MCP (Microsoft MCP Gateway, IBM ContextForge, Cloudflare Workers, etc.) pode fazer proxy deste servidor. Para gateways baseados em stdio, use o transporte padrão. Para gateways baseados em HTTP, inicie o servidor com o transporte http e aponte o gateway para o endpoint /mcp.

Docker

Compile e execute o servidor como um contêiner 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

O contêiner executa em modo HTTP na porta 3000 por padrão, com uma verificação de saúde integrada.

Kubernetes

Implante em um cluster Kubernetes usando os manifests fornecidos:

# 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

A implantação executa 2 réplicas com probes de readiness/liveness, limites de recursos e contexto de segurança não-root. O Service expõe a porta 80 internamente (direcionando para a porta 3000 do contêiner).

Configuração

O servidor carrega automaticamente as variáveis de ambiente de um arquivo .env na raiz do projeto, se existir. Copie .env.example para .env e preencha com seus valores. As variáveis de ambiente também podem ser definidas via shell ou configuração do cliente MCP.

Variável	Obrigatório	Padrão	Descrição
HARNESS_MCP_MODE	Não	single-user	Modo de implantação: single-user (chave de API na configuração, usada para todas as sessões) ou multi-user (somente HTTP, credenciais por sessão via cabeçalhos x-harness-api-key e opcionais x-harness-account-id)
HARNESS_API_KEY	Sim*	--	Token de acesso pessoal do Harness ou token de conta de serviço. Obrigatório no modo single-user. NÃO deve ser definido no modo multi-user
HARNESS_ACCOUNT_ID	Não	(do PAT/SAT)	Identificador da conta Harness. Extraído automaticamente de tokens PAT/SAT no modo de usuário único; sessões multiusuário podem fornecer o seu próprio via x-harness-account-id quando a chave de API não incorpora um
HARNESS_BASE_URL	Não	https://app.harness.io	URL base da API/interface do Harness para implantações HTTP locais via stdio ou auto-hospedadas. Defina isto para ambientes como https://harness0.harness.io ao executar o servidor você mesmo. Não afeta o endpoint hospedado gerenciado https://mcp.harness.io/mcp
HARNESS_FME_API_KEY	Não	--	Credencial opcional de usuário único/auto-hospedado para FME/Split Admin usada para recursos fme_. Pode ser uma chave de administrador Split legada ou um PAT/SAT do Harness com direito a FME. As chamadas FME vão diretamente para api.split.io, portanto credenciais de OAuth/roteamento de serviço hospedadas para APIs da plataforma Harness não autenticam essas solicitações. Não deve ser definido no modo multi-user; o FME deve usar a credencial x-harness-api-key de cada sessão. Se não definido, o FME usa como fallback um HARNESS_API_KEY não-placeholder para sessões auto-hospedadas
HARNESS_FME_BASE_URL	Não	https://api.split.io	URL base da API de administração Split/FME usada pelos recursos fme_. URLs HTTP exigem HARNESS_ALLOW_HTTP=true para desenvolvimento local
HARNESS_ORG	Não	--	ID da organização. Usado quando org_id não é especificado por chamada de ferramenta. Se omitido, org_id deve ser fornecido explicitamente. Os agentes também podem descobrir organizações dinamicamente via harness_list(resource_type="organization")
HARNESS_PROJECT	Não	--	ID do projeto. Usado quando project_id não é especificado por chamada de ferramenta. Os agentes também podem descobrir projetos dinamicamente via harness_list(resource_type="project")
HARNESS_API_TIMEOUT_MS	Não	30000	Tempo limite de solicitação HTTP em milissegundos
HARNESS_MAX_RETRIES	Não	3	Número de tentativas para falhas transitórias (429, 5xx)
HARNESS_MAX_BODY_SIZE_MB	Não	10	Tamanho máximo do corpo da solicitação HTTP em MB para transporte http
HARNESS_RATE_LIMIT_RPS	Não	10	Limitação de solicitações do lado do cliente (solicitações por segundo) para APIs do Harness
LOG_LEVEL	Não	info	Nível de verbosidade do log: debug, info, warn, error
HARNESS_TOOLSETS	Não	(padrões)	Lista de conjuntos de ferramentas separada por vírgulas. Vazio carrega os conjuntos de ferramentas padrão. Suporta +name para incluir explicitamente conjuntos de ferramentas opt-in e -name para remover padrões (consulte Filtragem de Conjuntos de Ferramentas)
HARNESS_READ_ONLY	Não	false	Bloqueia todas as operações de mutação (criar, atualizar, excluir, executar). Apenas listar e obter são permitidos. Útil para ambientes compartilhados/demonstração
HARNESS_AUTO_APPROVE_RISK	Não	none	Limite de aprovação automática baseado em risco para fluxos de trabalho autônomos. Operações com risco igual ou inferior a este prosseguem sem confirmação. Valores: none, low_write, medium_write, high_write, all. Consulte Elicitação
HARNESS_SKIP_ELICITATION	Não	false	Descontinuado — use HARNESS_AUTO_APPROVE_RISK=all em vez disso. Mantido para compatibilidade reversa
HARNESS_ALLOW_HTTP	Não	false	Permite HARNESS_BASE_URL não-HTTPS. Por padrão, o servidor aplica HTTPS por segurança. Defina como true apenas para desenvolvimento local contra uma instância Harness sem TLS
HARNESS_PIPELINE_VERSION	Não	0	(Alfa) Versão do YAML de pipeline. 0 carrega o tipo de recurso pipeline e exclui pipeline_v1; 1 carrega pipeline_v1 e exclui pipeline. Sessões HTTP podem substituir isso no momento da inicialização com x-harness-pipeline-version: 0 ou 1
HARNESS_MCP_ALLOWED_HOSTS	Não	--	Nomes de host permitidos separados por vírgulas pela validação do cabeçalho Host do transporte HTTP. mcp.harness.io é permitido por padrão para binds de localhost; adicione domínios de proxy/personalizados aqui
HARNESS_MCP_AUTH_TOKEN	Não	--	Token Bearer exigido nas rotas HTTP /mcp quando definido. Exigido por padrão quando o transporte HTTP faz bind em um host não-loopback
HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP	Não	false	Permitir explicitamente transporte HTTP não autenticado em binds não-loopback. Use apenas atrás de outro controle autenticado
HARNESS_MCP_TRUST_PROXY	Não	0	Número de saltos de proxy reverso / balanceador de carga para confiar na resolução de IP do cliente (Express trust proxy). Defina para a contagem de proxies à frente do servidor para que a limitação de taxa por IP use o cliente real em vez do peer do socket do proxy
HARNESS_MCP_LOG_FILE	Não	~/.claude/harness-mcp.log	Arquivo usado para diagnósticos de desconexão/queda do stdio quando o stderr pode não estar mais disponível
HARNESS_LOG_UNSAFE_BODIES	Não	false	Incluir corpos brutos de solicitação/resposta nos logs. Desativado por padrão, pois os corpos podem conter segredos; habilite apenas para depuração local
HARNESS_AUDIT_FILE	Não	--	Anexar eventos de auditoria a um arquivo JSON delimitado por nova linha para coleta local durável
HARNESS_AUDIT_WEBHOOK_URL	Não	--	Endpoint HTTPS que recebe eventos de auditoria em lote. URLs HTTP exigem HARNESS_ALLOW_HTTP=true para desenvolvimento local
HARNESS_AUDIT_WEBHOOK_TOKEN	Não	--	Token Bearer opcional enviado ao webhook de auditoria
HARNESS_AUDIT_WEBHOOK_BATCH_SIZE	Não	10	Número de eventos de auditoria a serem agrupados antes do flush do webhook
HARNESS_AUDIT_WEBHOOK_FLUSH_MS	Não	5000	Tempo máximo para reter eventos de auditoria antes do flush do webhook
OTEL_EXPORTER_OTLP_ENDPOINT	Não	--	Habilita spans de auditoria OpenTelemetry quando os pacotes opcionais do OpenTelemetry estão instalados
HARNESS_SEARCH_PROVIDER	Não	local	Backend de busca semântica: local (embeddings ONNX em processo, padrão), remote (serviço de busca externo via HTTP, obrigatório para modo multiusuário) ou none (desabilitar busca semântica, usar apenas scatter-gather por palavras-chave). Use none em ambientes isolados ou quando o carregamento do modelo na inicialização for indesejável
HARNESS_SEARCH_SERVICE_URL	Não	--	URL base do serviço de busca remoto quando HARNESS_SEARCH_PROVIDER=remote (ex.: http://search-svc:8080). Obrigatório ao usar o provedor remote
HARNESS_SEARCH_SERVICE_HEADERS	Não	--	Objeto JSON de cabeçalhos enviados com cada solicitação ao serviço de busca remoto. Suporta qualquer esquema de autenticação: {"Authorization":"Bearer tok"}, {"x-api-key":"key"}, ou vários cabeçalhos internos de serviço para serviço
HARNESS_HF_CACHE_DIR	Não	/tmp/hf-cache	Diretório para o cache de modelo @huggingface/transformers usado pelo provedor de busca local. A imagem Docker pré-inclui o modelo em /app/.cache/hf para evitar downloads em tempo de execução. Defina para um caminho de volume persistente em implantações de produção.
HARNESS_DIAGNOSE_LOG_FETCH_CONCURRENCY	Não	3	Máximo de downloads simultâneos de blobs de log emitidos por harness_diagnose ao buscar logs para etapas com falha. Aumente apenas se a latência de diagnóstico for dominada pelo tempo de relógio de busca de log e o pod tiver folga de memória.

Pesquisa Semântica

harness_search usa roteamento semântico para reduzir as chamadas de API scatter-gather antes de expandir para o Harness. Três provedores de busca estão disponíveis:

Provedor	Quando usar
local (padrão)	Modo stdio de usuário único. Executa all-MiniLM-L6-v2 no processo via @huggingface/transformers. Baixa o modelo de ~23 MB no primeiro uso; execuções subsequentes usam o cache.
remote	Modo HTTP multiusuário (hospedado pelo Harness). Delega a incorporação e a recuperação a um serviço de busca externo. O isolamento de locatário é aplicado via tenant_id — conhecimento estático/documentos usam global, dados de entidade por conta usam o ID da conta.
none	Desativa a busca semântica totalmente; volta para o scatter-gather por palavras-chave em todos os tipos de recurso.

Configuração do provedor remoto:

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

Testando o provedor remoto localmente com o serviço stub incluído (sem dependências externas):

# 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)

O stub (stub-search-service.py) implementa o mesmo contrato de /v1/health, /v1/ingest, e /v1/search que o serviço de busca de produção. Ele usa um simples embedding bag-of-chars, então nenhum download de modelo é necessário — os resultados são semanticamente plausíveis, mas não com qualidade de produção.

Aplicação de HTTPS

HARNESS_BASE_URL deve usar HTTPS por padrão. Se você definir uma URL não-HTTPS (por exemplo, http://localhost:8080), o servidor se recusará a iniciar com:

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

Registro de Auditoria

Todas as operações de API Harness despachadas pelo registro (list, get, create, update, delete e execute) emitem eventos de auditoria estruturados quando os sinks de auditoria estão configurados. Eventos de mutação incluem o caminho de confirmação usado pela elicitação ou aprovação automática quando um contexto de confirmação está presente; eventos de leitura atualmente omitem metadados de confirmação. Ferramentas de metadados locais e descoberta de esquema que contornam o registro, como harness_describe e harness_schema, não fazem parte desse fluxo de auditoria. Um sink stderr é registrado por padrão, mas passa pelo logger normal e obedece a LOG_LEVEL; configure sinks de arquivo ou webhook para coleta de auditoria durável:

• HARNESS_AUDIT_FILE anexa eventos JSON delimitados por nova linha para coleta local.
• HARNESS_AUDIT_WEBHOOK_URL envia lotes de { "events": [...] } para um webhook HTTPS, opcionalmente com HARNESS_AUDIT_WEBHOOK_TOKEN. Lotes com falha são reenfileirados com capacidade limitada e eventualmente descartados com um aviso, em vez de bloquear a execução da ferramenta.
• OTEL_EXPORTER_OTLP_ENDPOINT habilita spans de auditoria quando as dependências opcionais do OpenTelemetry estão instaladas. O sink reutiliza um provedor de tracer existente quando um está registrado; caso contrário, ele inicializa um exportador OTLP autônomo.

Cada evento inclui o nome da ferramenta, tipo de recurso, operação, identificadores, timestamp, risco, resultado, método HTTP/caminho, duração e método de confirmação quando aplicável. Os sinks de auditoria são telemetria de melhor esforço; problemas de entrega são registrados e nunca reproduzem ou alteram a operação de API Harness subjacente. Para detalhes de configuração de OTel e atributos de span, veja specs/005-otel-audit-sink.md.

Referência de Ferramentas

O servidor expõe 11 ferramentas MCP. A maioria das ferramentas de API aceita org_id e project_id como substituições opcionais — se omitidos, eles voltam para HARNESS_ORG e HARNESS_PROJECT. harness_describe é apenas metadados locais e não usa escopo de org/projeto.

Suporte a URL: A maioria das ferramentas voltadas para API aceita um parâmetro url — cole uma URL da UI do Harness e o servidor extrai automaticamente org, projeto, tipo de recurso, ID do recurso, ID do pipeline e ID de execução. harness_describe não aceita url.

Suporte a escopo: Tipos de recurso com variantes conta/org/projeto expõem supportedScopes em harness_describe. Passe resource_scope quando precisar de um nível específico:

• resource_scope: "account" envia apenas accountIdentifier.
• resource_scope: "org" envia accountIdentifier e orgIdentifier.
• resource_scope: "project" envia identificadores de conta, org e projeto.

Os recursos atuais com múltiplos escopos incluem connector, service, environment, infrastructure, secret, file_store e template. Se resource_scope for omitido, o registro usa o escopo padrão do recurso e as configurações padrão, exceto que recursos marcados como escopo opcional podem omitir org/projeto a menos que explicitamente passado. URLs do Harness também podem definir o escopo automaticamente quando o caminho contém contexto de nível de conta ou projeto.

Saída estruturada: Cada ferramenta declara um outputSchema do MCP. harness_list normaliza respostas do Harness do tipo lista em conteúdo estruturado em forma de objeto para que clientes estritos possam validar: matrizes de nível superior se tornam { "items": [...], "total": <count>, "page": <page> }, e chaves de wrapper comuns, como content, data, body, objects ou features são içadas para items quando necessário. A resposta de texto ainda contém o payload JSON compacto retornado a todos os clientes.

Ferramenta	Descrição
harness_describe	Descubra tipos de recurso, operações e campos disponíveis. Nenhuma chamada de API — retorna metadados locais do registro.
harness_schema	Busque definições exatas de YAML/JSON Schema e exemplos para criar/atualizar recursos. Esquemas de pipeline/template estão inclusos; esquemas de connector, environment, service, secret e infrastructure são esquemas de entidade cientes de escopo, obtidos de snapshots inclusos ou da /yaml-schema NG. Suporta exploração profunda via path.
harness_list	Liste recursos de um determinado tipo com filtragem, busca e paginação.
harness_get	Obtenha um único recurso pelo seu identificador.
harness_create	Crie um novo recurso. Suporta pipelines inline e remotos (com suporte a Git). Solicita confirmação do usuário via elicitação.
harness_update	Atualize um recurso existente. Suporta pipelines inline e remotos (com suporte a Git). Solicita confirmação do usuário via elicitação.
harness_delete	Exclua um recurso. Solicita confirmação do usuário via elicitação. Destrutivo.
harness_execute	Execute uma ação em um recurso (executar/reexecutar pipeline, importar pipeline do Git, alternar flag, sincronizar app). Solicita confirmação do usuário via elicitação. Para execuções de pipeline, use o fluxo de trabalho de entrada em tempo de execução abaixo (suporta expansão abreviada branch/tag/pr_number/commit_sha).
harness_search	Pesquise nos tipos de recurso do Harness com uma única consulta. Usa roteamento semântico (embeddings ONNX locais all-MiniLM-L6-v2, 384 dimensões) para prever tipos de recurso relevantes de um corpus knowledge indexado na inicialização — normalmente estreitando de ~163 tipos para 1–8 antes do scatter-gather. Cai para scatter-gather por palavras-chave completo quando a confiança semântica é baixa. A resposta inclui semantic_routed e types_skipped quando o roteamento é acionado. Veja docs/search-guidelines.md para saber como tornar novos tipos de recurso descobertos.
harness_diagnose	Diagnostique recursos pipeline, connector, delegate e gitops_application (aliases: execution -> pipeline, gitops_app -> gitops_application). Para pipelines, retorna tempo de estágio/etapa e detalhes de falha; para connectors/delegates/aplicativos GitOps, retorna sinais direcionados de saúde e solução de problemas.
harness_status	Obtenha um painel de saúde do projeto em tempo real — execuções recentes, taxas de falha e links diretos.

Fluxo de Trabalho de Consulta de Esquema

Use harness_schema antes de criar ou atualizar recursos com suporte a YAML para que agentes possam copiar nomes de campos e restrições exatos em vez de adivinhar a partir de prosa.

• Esquemas inclusos incluem pipeline, template, trigger, pipeline_v1, template_v1, inputSet_v1, overlayInputSet_v1 e agent-pipeline.
• Esquemas de entidade incluem connector, environment, service, secret e infrastructure. Eles são cientes de escopo (account, org ou project) e exigem org_id/project_id quando o escopo selecionado os requer.
• Snapshots de entidade fornecidos são usados primeiro quando correspondem à conta em execução; caso contrário, a ferramenta usa a API /yaml-schema NG do Harness e armazena o resultado em cache.
• Omita path para um resumo de campos/setores, depois passe um path separado por pontos para inspecionar uma definição aninhada.

Exemplos:

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

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

Os mantenedores podem atualizar os snapshots de entidade fornecidos com pnpm sync-entity-schemas quando os esquemas YAML de entidade do Harness mudam.

Exemplos de Ferramentas

Descubra quais recursos estão disponíveis:

{ "resource_type": "pipeline" }

Liste organizações na conta:

{ "resource_type": "organization" }

Liste projetos em uma organização:

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

Liste pipelines em um projeto:

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

Obtenha um serviço específico:

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

Execute um pipeline:

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

Alterne um feature flag:

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

Pesquise em todos os tipos de recurso:

{ "query": "payment-service" }

Diagnostique uma execução por ID (modo resumo — padrão):

{ "execution_id": "abc123XYZ" }

Diagnostique a partir de uma URL do Harness:

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

Diagnostique a conectividade do connector:

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

Diagnostique a saúde do delegate:

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

Diagnostique um aplicativo GitOps (com opções):

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

Obtenha o relatório de execução mais recente para um pipeline:

{ "pipeline_id": "my-pipeline" }

Modo de diagnóstico completo com YAML e logs de etapas com falha:

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

Modo resumo com logs habilitados (melhor dos dois mundos):

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

Obtenha o status de saúde do projeto:

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

Liste esquemas de banco de dados filtrados por tipo de migração:

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

Liste instâncias de banco de dados para um esquema:

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

Obtenha o pipeline de autoria LLM resolvido para um schema e instância:

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

Liste nomes de objetos de snapshot (ex.: tabelas) para uma instância de schema:

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

Obtenha metadados completos de snapshot para objetos nomeados específicos:

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

Fluxo de Execução de Pipeline (Recomendado)

Use esta sequência para reduzir erros de entrada em tempo de execução:

1. Descubra entradas de runtime necessárias

• harness_get(resource_type="runtime_input_template", resource_id="<pipeline_id>")
• O template retornado mostra os placeholders <+input> que precisam de valores.

2. Escolha a estratégia de entrada

• Variáveis simples: passe pares de chave-valor simples inputs (por exemplo, {"branch":"main","env":"prod"}).

• Entradas complexas/estruturais: use input_set_ids (blocos de CI codebase/build e entradas de template aninhadas são melhor tratados dessa forma).

• Chaves abreviadas de CI codebase (somente execução de pipeline):

  Chave abreviada	Estrutura expandida
  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>

• Restrição: a expansão abreviada é ignorada quando inputs.build já está presente (build explícito tem prioridade).

3. Execute a execução

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

• Para pipelines com suporte a Git cujo YAML deve ser carregado de uma branch não padrão, passe params.pipeline_branch (enviado ao Harness como pipelineBranchName):

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

4. Opcional: combine ambos

• Use input_set_ids para a forma base e inputs para substituições simples.

Se campos obrigatórios não forem resolvidos, a ferramenta retorna um erro de pré-execução com chaves esperadas e conjuntos de entrada sugeridos. Você pode inspecionar mapeamentos abreviados disponíveis com harness_describe(resource_type="pipeline") (executeActions.run.inputShorthands).

Execução Dinâmica de Pipeline

Use pipeline_dynamic_execution.run quando um agente ou sistema externo gera o YAML completo do pipeline v0 em tempo de execução e precisa executá-lo em um shell de pipeline Harness existente. Isso não substitui o pipeline.run normal: o pipeline v0 salvo já deve existir, a opção Allow Dynamic Execution em nível de conta e de pipeline deve estar habilitada, e o chamador precisa de permissões de Editar e Executar no pipeline.

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

Restrições:

• body deve ser um objeto com um campo yaml. Corpos de string brutos são rejeitados pelo schema público harness_execute.
• body.yaml pode ser uma string YAML ou um objeto de pipeline JSON; o JSON é serializado para YAML antes da solicitação.
• Os placeholders de <+input> em tempo de execução não são resolvidos por esta API. Envie YAML totalmente resolvido.
• Conjuntos de entrada, execução seletiva de estágios, repetição e gatilhos não são suportados pelo endpoint de execução dinâmica.
• A ação é high_write e usa o caminho normal de confirmação/aprovação automática. A resposta projeta o envelope da API para { "execution_id": "...", "status": "..." } e inclui um link de execução openInHarness quando os dados de escopo estão disponíveis.

Se o Harness rejeitar a execução como não habilitada, verifique tanto a configuração Allow Dynamic Execution em nível de conta quanto a opção em nível de pipeline em Pipeline -> Advanced Options -> Dynamic Execution Settings.

Análise Forense de Entradas de Execução

Use execution_inputs após uma execução para inspecionar o YAML de entrada mesclado que produziu uma execução específica. Isso é útil quando uma falha depende da mesclagem de conjuntos de entrada, branches de conjuntos de entrada com suporte a Git ou valores de gatilho/runtime que são difíceis de reconstruir apenas pela página de execução.

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

A resposta de get é projetada para:

• executionId - o ID de execução do plano de resource_id.
• inputSetYaml - YAML de entrada de runtime mesclado usado para a execução, ou null.
• inputSetTemplateYaml - template de entrada no momento da execução, ou null.
• resolvedYaml - YAML resolvido por expressão quando resolve_expressions=true, caso contrário, geralmente null.
• inputSetDetails - conjuntos de entrada salvos que contribuíram como pares { identifier, name }.
• inputSetBranchName - branch de origem para conjuntos de entrada com suporte a Git, ou null.

execution_inputs é somente leitura e de risco de leitura. Se resolve_expressions for omitido, o servidor omite os parâmetros de consulta da API e o Harness usa seu modo de resolução UNKNOWN padrão.

Modo de Espera de Execução de Pipeline

Para pipeline.run, pipeline.retry e pipeline_v1.run, passe wait: true para permitir que o servidor faça polling até que a execução atinja um status terminal. Isso mantém o lançamento do pipeline e a verificação de status em uma única chamada de ferramenta, em vez de pedir ao cliente ou ao LLM para executar um loop de polling.

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

Comportamento do modo de espera:

• O timeout padrão é de 600 segundos; a faixa permitida é de 10 segundos a 7200 segundos.
• O intervalo inicial de polling é de 3 segundos por padrão, faz backoff de 1,5x e atinge no máximo 30 segundos.
• Em caso de sucesso ou falha, a resposta inclui campos como execution_id, execution_status, execution_terminal, execution_elapsed_ms e execution_poll_count.
• Se o timeout ocorrer, o gatilho original ainda foi bem-sucedido; a resposta inclui execution_timed_out: true e _wait.hint com o último status observado.
• Se o polling falhar após o gatilho ser bem-sucedido, a resposta inclui _wait.error e uma dica de reverificação. Não reexecute o pipeline cegamente, a menos que você tenha confirmado que a primeira execução não está em andamento.
• Os status terminais de falha incluem _diagnose_hint apontando para harness_diagnose(resource_type="execution", options={execution_id: "..."}).

Peça ao Agente DevOps de IA para criar um pipeline:

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

Atualize um serviço por meio de linguagem natural:

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

Modos de Armazenamento de Pipeline

Os pipelines do Harness podem ser armazenados de três formas:

Modo	Descrição	Quando usar
Inline	YAML do pipeline armazenado no Harness	Padrão. Configuração mais simples, sem necessidade de Git.
Remoto (Git Externo)	YAML do pipeline armazenado em GitHub, GitLab, Bitbucket, etc.	Equipes que usam pipeline-como-código com suporte a Git com um provedor externo.
Remoto (Harness Code)	YAML do pipeline armazenado em um repositório Harness Code	Equipes que usam o serviço de hospedagem Git integrado do Harness.

Crie um pipeline inline (padrão):

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

Crie um pipeline remoto (Git Externo — ex.: 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"
  }
}

Crie um pipeline remoto (Harness Code — sem necessidade de conector):

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

Atualize um pipeline remoto:

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

Importe um pipeline de um repositório Git externo:

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

Importe um pipeline de um repositório 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"
  }
}

Crie um conector:

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

Exclua um gatilho:

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

Liste conjuntos de entrada para um pipeline:

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

Obtenha um conjunto de entrada específico:

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

Crie um conjunto de entrada:

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

Atualize um conjunto de entrada:

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

Exclua um conjunto de entrada:

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

Tipos de Recursos

224 tipos de recursos organizados em 38 conjuntos de ferramentas. Cada tipo de recurso suporta um subconjunto de operações CRUD e ações de execução opcionais.

Plataforma

Tipo de Recurso	Lista	Obter	Criar	Atualizar	Excluir	Ações de Execução
organization	x	x	x	x	x
project	x	x	x	x	x

Pipelines

Tipo de Recurso	Lista	Obter	Criar	Atualizar	Excluir	Ações de Execução
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
approval_instance	x					approve, reject

Apenas um tipo de recurso de YAML de pipeline é carregado na inicialização. Por padrão, HARNESS_PIPELINE_VERSION=0 expõe pipeline e oculta pipeline_v1; defina HARNESS_PIPELINE_VERSION=1 para expor pipeline_v1 e ocultar pipeline. No modo HTTP, inclua x-harness-pipeline-version: 0 ou 1 na solicitação initialize para escolher a versão para essa sessão.

Agentes de IA

Tipo de Recurso	Lista	Obter	Criar	Atualizar	Excluir	Ações de Execução
agent	x	x	x	x	x
agent_run	x

Serviços

Tipo de Recurso	Lista	Obter	Criar	Atualizar	Excluir	Ações de Execução
service	x	x	x	x	x

Ambientes

Tipo de Recurso	Lista	Obter	Criar	Atualizar	Excluir	Ações de Execução
environment	x	x	x	x	x	move_configs

Conectores

Tipo de Recurso	Lista	Obter	Criar	Atualizar	Excluir	Ações de Execução
connector	x	x	x	x	x	test_connection
connector_catalogue	x

Infraestrutura

Tipo de Recurso	Lista	Obter	Criar	Atualizar	Excluir	Ações de Execução
infrastructure	x	x	x	x	x	move_configs

Segredos

Tipo de Recurso	Lista	Obter	Criar	Atualizar	Excluir	Ações de Execução
secret	x	x

Logs de Execução

Tipo de Recurso	Lista	Obter	Criar	Atualizar	Excluir	Ações de Execução
execution_log		x

Trilha de Auditoria

Tipo de Recurso	Lista	Obter	Criar	Atualizar	Excluir	Ações de Execução
audit_event	x	x

Delegates

Tipo de Recurso	Lista	Obter	Criar	Atualizar	Excluir	Ações de Execução
delegate	x
delegate_token	x	x	x		x	revoke, get_delegates

Repositórios de Código

Resource Type	List	Get	Create	Update	Delete	Execute Actions
repository	x	x	x	x
branch	x	x	x		x
commit	x	x	x			diff, diff_stats
file_content		x				blame
tag	x		x		x
repo_rule	x	x
space_rule	x	x

A criação de commit submete uma ou mais ações de arquivo diretamente pela API do Harness Code, sem clonagem. Passe body.title, body.branch e body.actions; cada ação é CREATE, UPDATE, DELETE ou MOVE, e UPDATE exige o SHA do blob atual.

Registros de Artefatos

Resource Type	List	Get	Create	Update	Delete	Execute Actions
registry	x	x
artifact	x
artifact_version	x
artifact_file	x

Armazenamento de Arquivos

Resource Type	List	Get	Create	Update	Delete	Execute Actions
file_store	x	x	x	x	x	list_children

file_store gerencia arquivos e pastas do Harness File Store por meio das ferramentas genéricas. Ele suporta escopo de conta, organização e projeto; passe resource_scope="account"|"org"|"project" ou cole uma URL do Harness File Store para que o servidor possa derivar o escopo e os IDs.

Chamadas comuns:

# 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"})

Restrições do corpo multipart:

• Criação/atualização aceitam JSON body e depois o convertem para multipart/form-data para /ng/api/file-store.
• name, type (FILE ou FOLDER) e parent_identifier são obrigatórios; use o literal "Root" apenas para a raiz do escopo selecionado.
• A criação de FILE exige exatamente um de content (string UTF-8) ou content_base64 (base64 válido e não vazio). A atualização de FILE pode omitir o conteúdo para atualizações apenas de metadados, ou fornecer exatamente um campo de conteúdo para substituir o conteúdo.
• A criação/atualização de FOLDER deve omitir content e content_base64.
• O file_usage opcional deve ser MANIFEST_FILE, CONFIG ou SCRIPT; metadados escalares opcionais, como description, mime_type, path e tags, devem ser strings.
• O conteúdo do upload é limitado a 100 MB. Os prompts de confirmação ocultam as prévias de content, content_base64 e contentBase64 antes da elicitação.

list_children aceita tanto a forma abreviada (resource_id mais params.folder_name, ou params.file_store_id/params.folder_identifier mais params.folder_name) quanto um FileStoreNode completo body com identifier, name e type: "FOLDER". Corpos completos usam camelCase do Harness parentIdentifier; a forma abreviada pode usar params.parent_identifier.

Modelos

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

As operações de modelo usam os caminhos do serviço de Templates do Harness (/template/api/templates...). A criação e a atualização exigem a string YAML completa do modelo em body.template_yaml ou body.yaml; version_label tem como alvo uma versão específica para atualização/exclusão, enquanto excluir sem version_label exclui todas as versões.

Painéis

Resource Type	List	Get	Create	Update	Delete	Execute Actions
dashboard	x	x
dashboard_data		x

DevOps de Banco de Dados

Resource Type	List	Get	Create	Update	Delete	Execute Actions
database_schema	x	x	x	x	x
database_instance	x	x	x	x	x
database_snapshot_object	x	x
database_llm_authoring_pipeline		x

Gerenciamento de Infraestrutura como Código (IaCM)

Os recursos do IaCM são habilitados por padrão e, em sua maioria, têm escopo de projeto. Comece com iacm_workspace para encontrar identificadores de workspace e, em seguida, use esse workspace_id para recursos de workspace, custos e diffs de atividade. Use iacm_variable_set para conjuntos de variáveis reutilizáveis no escopo de conta, organização ou projeto. O registro de módulos tem escopo de conta.

A criação/atualização de iacm_workspace retorna apenas { policy_evaluation } — acompanhe com harness_get para buscar o workspace. A criação/atualização de iacm_variable_set retorna o próprio recurso VariableSet. A atualização de variable-set é HTTP PUT com coleções de substituição completa — sempre faça harness_get primeiro e depois faça PUT do corpo desejado completo (terraform_variables / environment_variables são obrigatórios na atualização; omitir/vazio limpa conectores e arquivos de variáveis). As gravações são medium_write e exigem confirmação (elicitação ou confirm: true).

O RBAC de variable-set (iac_variableset_*) está atualmente Experimental no Harness — as verificações de acesso sempre permitem até que o iac-server ative a aplicação. O MCP ainda encaminha o PAT/SAT do chamador inalterado.

Resource Type	List	Get	Create	Update	Delete	Execute Actions
iacm_workspace	x	x	x	x
iacm_variable_set	x	x	x	x
iacm_resource	x
iacm_module	x	x
iacm_workspace_costs	x
iacm_activity_resource_change	x

Fluxo de trabalho típico:

1. harness_list(resource_type="iacm_workspace", org_id="...", project_id="...") para encontrar o workspace.
2. harness_create / harness_update em iacm_workspace para criar do zero ou a partir de um modelo (associated_template), ou atualizar um workspace existente — a resposta é apenas { policy_evaluation }.
3. harness_get(resource_type="iacm_workspace", workspace_id="...") para buscar o workspace criado/atualizado.
4. harness_list / harness_create / harness_update em iacm_variable_set (opcionalmente com resource_scope) para conjuntos de variáveis reutilizáveis de Terraform/env — a resposta é o recurso VariableSet.
5. harness_list(resource_type="iacm_resource", org_id="...", project_id="...", workspace_id="...") para inspecionar recursos, saídas e fontes de dados do Terraform.
6. harness_list(resource_type="iacm_workspace_costs", org_id="...", project_id="...", workspace_id="...") para revisar entradas de custo por execução.
7. harness_list(resource_type="iacm_activity_resource_change", org_id="...", project_id="...", activity_id="...", workspace_id="...") para inspecionar diffs de recursos antes/depois para uma atividade de plan, apply ou destroy.

As respostas de listagem do IaCM expõem page_count como a contagem apenas da página atual (exceto iacm_variable_set, que não é paginado). Quando has_more for verdadeiro, continue solicitando a próxima página baseada em 1 e some as contagens das páginas se precisar de um total.

Portal Interno do Desenvolvedor (IDP)

Resource Type	List	Get	Create	Update	Delete	Execute Actions
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

Solicitações de Pull

Resource Type	List	Get	Create	Update	Delete	Execute Actions
pull_request	x	x	x	x		close, merge
pr_reviewer	x		x			submit_review
pr_comment	x		x
pr_check	x
pr_activity	x

Use harness_execute(resource_type="pull_request", action="close", ...) para uma operação de fechamento explícita. harness_update também aceita body.state (open ou closed) e roteia mudanças de estado para o endpoint dedicado de estado de PR do Harness Code; envie edições de título/descrição em uma chamada de atualização separada.

Flags de Recursos

Resource Type	List	Get	Create	Update	Delete	Execute Actions
fme_workspace	x
fme_environment	x
fme_feature_flag	x	x	x	x	x	kill, restore, archive, unarchive
fme_feature_flag_definition		x	x	x
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
Recursos FME (Split.io) — fme_* recursos usam a API Split.io (api.split.io) e são escopados por ID do workspace, em vez de org/projeto. No modo de usuário único/self-hosted, a autenticação usa um token Bearer de HARNESS_FME_API_KEY, com fallback para um HARNESS_API_KEY que não é placeholder. HARNESS_FME_API_KEY pode ser uma chave de administrador Split legada ou um PAT/SAT do Harness com direito a FME, mas é rejeitado no modo multi-user para que implantações compartilhadas não possam substituir a credencial de cada usuário da sessão. Credenciais OAuth/roteamento de serviço hospedadas para APIs da plataforma Harness não autenticam solicitações diretas ao Split.io. fme_feature_flag oferece suporte ao gerenciamento completo do ciclo de vida: criar (requer traffic_type_id), listar, obter, atualizar metadados, excluir e executar ações de kill/restore/archive/unarchive. Use fme_traffic_type para descobrir IDs de tipo de tráfego, fme_identity para criar/atualizar atributos de identidade, e fme_standard_segment / fme_segment_keys para inspecionar segmentos padrão e adicionar chaves de membro. fme_rule_based_segment fornece CRUD para segmentos de segmentação, enquanto fme_rule_based_segment_definition gerencia regras de segmento específicas do ambiente com fluxos de aprovação de solicitação de alteração e ativação/desativação.

GitOps

Resource Type	List	Get	Create	Update	Delete	Execute Actions
gitops_agent	x	x
gitops_application	x	x				sync
gitops_cluster	x	x
gitops_repository	x	x
gitops_applicationset	x	x
gitops_repo_credential	x	x
gitops_app_event	x
gitops_pod_log		x
gitops_managed_resource	x
gitops_resource_action	x
gitops_dashboard		x
gitops_app_resource_tree		x

Chaos Engineering

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

Cloud Cost Management (CCM)

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

Software Engineering Insights (SEI)

Os recursos SEI são consolidados para eficiência de token. Use os parâmetros metric ou aspect para DORA, detalhes de equipe/árvore organizacional e insights de IA.

Resource Type	List	Get	Create	Update	Delete	Execute Actions
sei_metric	x
sei_productivity_metric		x
sei_dora_metric		x				Passe metric: deployment_frequency, change_failure_rate, mttr, lead_time, or *_drilldown
sei_team	x	x
sei_team_detail	x					Passe aspect: integrations, developers, integration_filters
sei_org_tree	x	x
sei_org_tree_detail	x	x				Passe aspect: efficiency_profile, productivity_profile, business_alignment_profile, integrations, teams
sei_business_alignment	x	x				Passe aspect: feature_metrics, feature_summary, drilldown para get
sei_ai_usage	x	x				Passe aspect: metrics, breakdown, summary, top_languages
sei_ai_adoption	x	x				Passe aspect: metrics, breakdown, summary
sei_ai_impact		x				Passe aspect: pr_velocity, rework
sei_ai_raw_metric	x

Garantia da Cadeia de Suprimentos de Software (SCS)

Resource Type	List	Get	Create	Update	Delete	Execute Actions
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

Cofre de Evidências

O Cofre de Evidências armazena atestações in-toto (evidências de SDLC). A listagem suporta escopo de conta/org/projeto via resource_scope. Filtros de texto livre individual (pipeline, artefato isolado, gitoid) usam search_term; uma restrição adicional de Nome usa filters.subject_name; o resumo (digest) do conteúdo do sujeito usa filters.subject_digest. Get pesquisa por gitoid_sha256 e requer org_id/project_id (da linha da lista). Download (ação harness_execute download) retorna um download_url com tempo limitado — sempre mostre esse link ao usuário. Requer feature flag SCS_EVIDENCE_VAULT.

Resource Type	List	Get	Create	Update	Delete	Execute Actions
attestation	x	x				download

Orquestração de Testes de Segurança (STO)

Resource Type	List	Get	Create	Update	Delete	Execute Actions
security_issue	x
security_issue_filter	x
security_exemption	x		x			approve, reject
remediation_diff	x

security_exemption create é uma operação high_write. O servidor deriva requester_id do PAT autenticado, define exemptFutureOccurrences=true e define duration_days como padrão como 30 quando não fornecido. Para listar isenções, passe um tamanho de página explícito pequeno (por exemplo filters: { "status": "Pending", "size": 5 }) e siga o _nextPageHint retornado em cada resposta.

Fluxo de trabalho de execução de isenção de segurança:

• Use harness_list com resource_type="security_exemption" e um status explícito, como Pending, Approved, Rejected, Expired ou Canceled.
• Use harness_execute com action="approve" e um body.scope obrigatório: CURRENT, ACCOUNT, ORG ou PROJECT. CURRENT aprova no escopo existente da isenção; os outros escopos usam o endpoint de promoção do STO internamente. O servidor preenche automaticamente body.approver_id a partir do usuário autenticado quando omitido; body.comment é opcional.
• Use action="reject" para rejeitar uma isenção. body.approver_id também é preenchido automaticamente quando omitido.
• Não há uma ação de execução promote separada. Use action="approve" com um body.scope não CURRENT quando o resultado solicitado for aprovação no escopo de conta, organização ou projeto.

Controle de Acesso

Resource Type	List	Get	Create	Update	Delete	Execute Actions
user	x	x
user_group	x	x	x		x
service_account	x	x	x		x
role	x	x	x		x
role_assignment	x		x
resource_group	x	x	x		x
permission	x

Governança

Resource Type	List	Get	Create	Update	Delete	Execute Actions
policy	x	x	x	x	x
policy_set	x	x	x	x	x
policy_evaluation	x	x

Congelamento de Implantação

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

Substituições de Serviço

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

Configurações

Resource Type	List	Get	Create	Update	Delete	Execute Actions
setting	x

Prompts MCP

DevOps

Prompt	Descrição	Parâmetros
build-deploy-app	Fluxo de trabalho CI/CD de ponta a ponta: escanear um repositório git, gerar pipeline de CI (build e push da imagem Docker), descobrir ou gerar manifests K8s, criar pipeline de CD e fazer deploy — com nova tentativa automática em falhas de CI (até 5 tentativas) e falhas de CD (até 3 tentativas com permissão do usuário). Quando as tentativas se esgotam, fornece links profundos da UI do Harness para todos os recursos criados, para investigação manual.	repoUrl (obrigatório), imageName (obrigatório), projectId (opcional), namespace (opcional)
debug-pipeline-failure	Analisar uma execução com falha: aceita um ID de execução, ID de pipeline ou URL do Harness. Obtém detalhamento de estágios/etapas, detalhes de falha, informações do delegate e logs da etapa com falha via harness_diagnose, e então fornece análise de causa raiz e correções sugeridas. Segue automaticamente falhas encadeadas de pipelines.	executionId (opcional), projectId (opcional)
pipeline_summarizer	Buscar e resumir TODOS os logs de etapas de uma execução de pipeline. Usa harness_diagnose com include_logs: true, include_all_step_logs: true para obter o log de cada etapa e, em seguida, apresenta uma tabela com Nome da Etapa, Status, Duração e O que Aconteceu (resumo baseado em log). NÃO pula nenhuma etapa.	executionId (opcional), projectId (opcional)
create-pipeline	Gerar um novo YAML de pipeline a partir de requisitos em linguagem natural, revisando recursos existentes para contexto	description (obrigatório), projectId (opcional)
create-agent	Construir interativamente um agente de IA do Harness — verificar agentes existentes, coletar requisitos, gerar especificação YAML do agente usando o esquema agent-pipeline, confirmar com o usuário e, em seguida, criar ou atualizar via harness_create/harness_update	agent_name (obrigatório), task_description (obrigatório), org_id (opcional), project_id (opcional)
onboard-service	Orientar a integração de um novo serviço com ambientes e um pipeline de deploy	serviceName (obrigatório), projectId (opcional)
dora-metrics-review	Revisar métricas DORA (frequência de deploy, taxa de falha de mudança, MTTR, lead time) com classificação Elite/Alto/Médio/Baixo e recomendações de melhoria	teamRefId (opcional), dateStart (opcional), dateEnd (opcional)
setup-gitops-application	Orientar a integração de um aplicativo GitOps — verificar agente, cluster, repositório e criar o aplicativo	agentId (obrigatório), projectId (opcional)
chaos-resilience-test	Projetar um experimento de caos para testar a resiliência do serviço com injeção de falhas, sondas e resultados esperados	serviceName (obrigatório), projectId (opcional)
feature-flag-rollout	Planejar e executar um rollout progressivo de feature flag entre ambientes com portões de segurança	flagIdentifier (obrigatório), projectId (opcional)
migrate-pipeline-to-template	Analisar um pipeline existente e extrair templates reutilizáveis de estágios/etapas dele	pipelineId (obrigatório), projectId (opcional)
delegate-health-check	Verificar conectividade do delegate, saúde, status do token e solucionar problemas de infraestrutura	projectId (opcional)
developer-portal-scorecard	Revisar scorecards do IDP para serviços e identificar lacunas para melhorar a experiência do desenvolvedor	projectId (opcional)
pending-approvals	Encontrar execuções de pipeline aguardando aprovação, mostrar detalhes e oferecer aprovação ou rejeição	projectId (opcional), orgId (opcional), pipelineId (opcional)

FinOps

Prompt	Descrição	Parâmetros
optimize-costs	Analisar dados de custo da nuvem, apresentar recomendações e anomalias, priorizadas por economia potencial	projectId (opcional)
cloud-cost-breakdown	Aprofundar-se nos custos de nuvem por serviço, ambiente ou cluster com análise de tendências e detecção de anomalias	perspectiveId (opcional), projectId (opcional)
commitment-utilization-review	Analisar a utilização de instâncias reservadas e planos de economia para encontrar desperdício e otimizar compromissos	projectId (opcional)
cost-anomaly-investigation	Investigar anomalias de custo — determinar causa raiz, recursos impactados e remediação	projectId (opcional)
rightsizing-recommendations	Revisar e priorizar recomendações de redimensionamento, opcionalmente criar tickets no Jira ou ServiceNow	projectId (opcional), minSavings (opcional)

DevSecOps

Prompt	Descrição	Parâmetros
security-review	Revisar problemas de segurança nos recursos do Harness e sugerir remediações por gravidade	projectId (opcional), severity (opcional, padrão: critical,high)
vulnerability-triage	Triar vulnerabilidades de segurança em pipelines e artefatos, priorizar por gravidade e explorabilidade	projectId (opcional), severity (opcional)
sbom-compliance-check	Auditar SBOM e postura de conformidade para artefatos — riscos de licença, violações de política, vulnerabilidades de componentes	artifactId (opcional), projectId (opcional)
supply-chain-audit	Auditoria de segurança de cadeia de suprimentos de software de ponta a ponta — proveniência, cadeia de custódia, conformidade com políticas	projectId (opcional)
security-exemption-review	Revisar isenções de segurança pendentes e tomar decisões de aprovação ou rejeição em lote	projectId (opcional)
bulk-exemption-create	Criar isenções de segurança justificadas para múltiplos problemas de STO com orientação explícita de escopo e duração	projectId (obrigatório), exemption_type (obrigatório), reason (obrigatório), filtros de problemas (opcional)
access-control-audit	Auditar permissões de usuário, contas com privilégios excessivos e atribuições de funções para aplicar o princípio do menor privilégio	projectId (opcional), orgId (opcional)

Harness Code

Prompt	Descrição	Parâmetros
code-review	Revisar um pull request — analisar diff, commits, verificações e comentários para fornecer feedback estruturado sobre bugs, segurança, desempenho e estilo	repoId (obrigatório), prNumber (obrigatório), projectId (opcional)
pr-summary	Gerar automaticamente um título e descrição de PR a partir do histórico de commits e diff de um branch	repoId (obrigatório), sourceBranch (obrigatório), targetBranch (opcional, padrão: main), projectId (opcional)
branch-cleanup	Analisar branches em um repositório e recomendar branches obsoletos ou mesclados para exclusão	repoId (obrigatório), projectId (opcional)

Recursos MCP

Resource URI	Descrição	Tipo MIME
pipeline:///{pipelineId}	Definição de YAML de pipeline	application/x-yaml
pipeline:///{orgId}/{projectId}/{pipelineId}	YAML de pipeline (com escopo explícito)	application/x-yaml
executions:///recent	Resumos das últimas 10 execuções de pipeline	application/json
schema:///pipeline	Esquema JSON de pipeline do Harness	application/schema+json
schema:///template	Esquema JSON de template do Harness	application/schema+json
schema:///trigger	Esquema JSON de trigger do Harness	application/schema+json
schema:///pipeline_v1 (Alpha)	Esquema JSON de pipeline V1 do Harness (formato simplificado de stages/steps)	application/schema+json
schema:///agent-pipeline	Esquema JSON de pipeline do agente de IA do Harness	application/schema+json

Filtragem de Toolsets

Por padrão, 38 de 39 toolsets estão habilitados. Um toolset é opcional e excluído dos padrões:

• ansible — Harness Ansible (inventories, playbooks, hosts, activity). Opcional porque é escopado por projeto e adiciona conceitos que muitos usuários não precisam.

Adicionando toolsets com o prefixo +

Use o prefixo + para incluir explicitamente toolsets opcionais junto com todos os padrões:

# Explicitly include Ansible alongside all defaults
HARNESS_TOOLSETS=+ansible

Removendo toolsets padrão

Use o prefixo - para excluir toolsets que você não precisa:

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

Combinando + e -

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

Lista de permissões explícita

Uma lista explícita separada por vírgulas (sem prefixos) substitui os padrões por completo. Apenas os toolsets listados são habilitados:

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

Nomes de toolsets disponíveis:

Conjunto de Ferramentas	Tipos de Recursos
platform	organization, project
pipelines	pipeline, pipeline_v1, pipeline_dynamic_execution, execution, execution_inputs, trigger, pipeline_summary, input_set, approval_instance
agents	agent, agent_run
services	service
environments	environment
connectors	connector, connector_catalogue
infrastructure	infrastructure
secrets	secret
logs	execution_log
audit	audit_event
delegates	delegate, delegate_token
repositories	repository, branch, commit, file_content, tag, repo_rule, space_rule
registries	registry, artifact, artifact_version, artifact_file
file_store	file_store
templates	template
dashboards	dashboard, dashboard_data
idp	idp_entity, scorecard, scorecard_check, scorecard_stats, scorecard_check_stats, idp_score, idp_workflow, idp_tech_doc
pull-requests	pull_request, pr_reviewer, pr_comment, pr_check, pr_activity
feature-flags	fme_workspace, fme_environment, fme_feature_flag, fme_feature_flag_definition, fme_rollout_status, fme_rule_based_segment, fme_rule_based_segment_definition, fme_traffic_type, fme_identity, fme_standard_segment, fme_segment_keys
gitops	gitops_agent, gitops_application, gitops_cluster, gitops_repository, gitops_applicationset, gitops_repo_credential, gitops_app_event, gitops_pod_log, gitops_managed_resource, gitops_resource_action, gitops_dashboard, gitops_app_resource_tree
chaos	chaos_experiment, chaos_experiment_run, chaos_experiment_variable, chaos_component_variable, chaos_input_set, chaos_experiment_template, chaos_probe, chaos_probe_in_run, chaos_probe_template, chaos_infrastructure, chaos_k8s_infrastructure, chaos_environment, chaos_hub, chaos_hub_fault, chaos_fault, chaos_fault_template, chaos_fault_experiment_run, chaos_action, chaos_action_template, chaos_loadtest, chaos_application_map, discovered_namespace, discovered_service, discovered_network_map, chaos_guard_condition, chaos_guard_rule, chaos_recommendation, chaos_risk, chaos_dr_test, scanned_risk, chaos_risk_rule, chaos_risk_scan
ccm	cost_perspective, cost_breakdown, cost_timeseries, cost_summary, cost_recommendation, cost_anomaly, cost_anomaly_summary, cost_category, cost_account_overview, cost_filter_value, cost_recommendation_stats, cost_recommendation_detail, cost_commitment
sei	sei_metric, sei_productivity_metric, sei_dora_metric, sei_team, sei_team_detail, sei_org_tree, sei_org_tree_detail, sei_business_alignment, sei_ai_usage, sei_ai_adoption, sei_ai_impact, sei_ai_raw_metric
scs	scs_artifact_source, artifact_security, scs_artifact_component, scs_artifact_remediation, scs_chain_of_custody, scs_compliance_result, code_repo_security, scs_sbom
evidence-vault	attestation
sto	security_issue, security_issue_filter, security_exemption, remediation_diff
dbops	database_schema, database_instance, database_snapshot_object, database_llm_authoring_pipeline
access_control	user, user_group, service_account, role, role_assignment, resource_group, permission
governance	policy, policy_set, policy_evaluation
freeze	freeze_window, global_freeze
overrides	service_override
settings	setting
knowledge-graph	kg_queryable_type_summary, kg_grammar, hql_query
semantic-layer	kg_type, kg_related_type
ai-evals	eval_dataset, eval_dataset_item, evaluation, eval_run, eval_run_item, eval_run_by_eval, eval_metric, eval_metric_set, eval_metric_set_entry, eval_suite, eval_suite_evaluation, eval_suite_run, eval_target, eval_annotation, eval_analytics, eval_git_settings, eval_registry_item, eval_git_registration, online_eval
iacm	iacm_workspace, iacm_variable_set, iacm_resource, iacm_module, iacm_workspace_costs, iacm_activity_resource_change
ansible (opt-in)	ansible_inventory, ansible_playbook, ansible_host, ansible_host_activity, ansible_activity

Arquitetura

                 +------------------+
                 |   AI Agent       |
                 |  (Claude, etc.)  |
                 +--------+---------+
                          |  MCP (stdio or HTTP)
                 +--------v---------+
                |    MCP Server     |
                | 11 Generic Tools  |
                 +--------+---------+
                          |
                 +--------v---------+
                |    Registry       |  <-- Declarative resource definitions
                |  38 Toolsets      |      (data files, not code)
                |  224 Resource Types|
                 +--------+---------+
                          |
                 +--------v---------+
                 |  HarnessClient    |  <-- Auth, retry, rate limiting
                 +--------+---------+
                          |  HTTPS
                 +--------v---------+
                 |  Harness REST API |
                 +-------------------+

Como Funciona

1. Ferramentas são verbos genéricos: harness_list, harness_get, etc. Elas aceitam um parâmetro resource_type que roteia para o endpoint correto da API.
2. O Registro mapeia cada resource_type para um ResourceDefinition — uma estrutura de dados declarativa que especifica o método HTTP, o caminho da URL, os mapeamentos de parâmetros de caminho/consulta e a lógica de extração de resposta.
3. Dispatch resolve a definição do recurso, constrói a requisição HTTP (substituição de caminho, parâmetros de consulta, injeção de conta/org/projeto ciente de resource_scope), chama a API Harness através de HarnessClient, e extrai os dados de resposta relevantes.
4. Filtragem de toolset (HARNESS_TOOLSETS) controla quais definições de recursos são carregadas no registro na inicialização.
5. Saída estruturada é declarada com MCP outputSchema; harness_list converte arrays e wrappers comuns de listas em structuredContent em formato de objeto para clientes estritos.
6. Deep links são automaticamente anexados às respostas, fornecendo URLs diretas da interface Harness para cada recurso.
7. Modo compacto remove metadados verbosos de resultados de listas, mantendo apenas campos acionáveis (identidade, status, tipo, timestamps, deep links) para minimizar o uso de tokens.

Adicionar um Novo Tipo de Recurso

Crie um novo arquivo em src/registry/toolsets/ ou adicione um recurso a um toolset existente:

// 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",
        },
      },
    },
  ],
};

Em seguida, importe-o em src/registry/index.ts e adicione-o ao array ALL_TOOLSETS. Nenhuma alteração é necessária nos arquivos de ferramentas.

Desenvolvimento

# 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

Estrutura do Projeto

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

Elicitação

As ferramentas de escrita (harness_create, harness_update, harness_delete, harness_execute) usam elicitação MCP para solicitar confirmação do usuário quando o risco da ação assim o exige — operações de medium_write, high_write e destructive apenas. Creates / updates / reads de baixo risco (ex.: pipeline.create, pipeline.update, hql_query.run) prosseguem silenciosamente sem prompt. Quando um prompt é exibido, o usuário vê o que está prestes a acontecer e aceita ou recusa, dando aprovação real com humano no circuito para as operações que realmente alteram ou executam coisas.

Como funciona:

1. O LLM chama uma ferramenta de escrita com risco medium_write+ (ex.: harness_delete, harness_execute pipeline.run). Creates / updates / reads de baixo risco não exibem prompt.
2. O servidor envia uma solicitação de elicitação ao cliente com um resumo da operação e uma caixa de seleção confirm (marcada por padrão).
3. O usuário vê os detalhes e clica em Aceitar (com confirm marcado) ou Recusar / Cancelar.
4. Se aceito com confirm: true, a operação prossegue. Se aceito com confirm desmarcado, recusado ou cancelado, é bloqueado e o LLM é informado (uma recusa explícita é autoritativa e não é contornada por confirm: true na chamada da ferramenta).

Suporte do cliente:

Cliente	Suporte a Elicitação
Cursor	Sim
VS Code (Copilot)	Sim
Claude Desktop	Ainda não
Devin Desktop	Ainda não
MCP Inspector	Sim

O comportamento de elicitação varia conforme o risco da operação quando o suporte ao cliente está ausente:

Nível de Risco	Cliente suporta elicitação	confirm: true passado	Comportamento
read, low_write	qualquer	qualquer	Prossegue silenciosamente — nenhum prompt é exibido (confirm não tem efeito neste nível de risco)
medium_write, high_write, destructive	Sim	qualquer	Mostra prompt ao usuário. Prossegue apenas se o usuário aceitar com confirm: true (o padrão do schema). Uma recusa explícita, cancelamento ou aceite com confirm: false (usuário desmarcou a caixa) é autoritativo e não é contornado por confirm: true na chamada da ferramenta. Um aceite ausente do campo confirm é tratado como falha do cliente em exibir um prompt utilizável — recuperável ao tentar novamente com confirm: true
medium_write, high_write, destructive	Não	Não	BLOQUEIA (retorna erro com dica para tentar novamente com confirm: true)
medium_write, high_write, destructive	Não	Sim	Prossegue (opt-in explícito para automação não interativa)
qualquer (até HARNESS_AUTO_APPROVE_RISK)	qualquer	qualquer	Aprova automaticamente sem prompt

Se elicitInput falhar em tempo de execução (erro de transporte, método não suportado) para uma operação medium_write+, a chamada é bloqueada a menos que o chamador passe confirm: true. confirm: true é respeitado como fallback quando o cliente não conseguiu exibir um prompt ou retornou um aceite degenerado ({action: "accept"} sem o campo de confirmação), mas não substitui uma recusa/cancelamento explícito de um cliente que completou o handshake de elicitação.

Modo Autônomo

Modo autônomo significa que o servidor prossegue com todas as operações — incluindo escritas e ações destrutivas — sem solicitar confirmação. Habilite-o configurando:

HARNESS_AUTO_APPROVE_RISK=all

Este é o teto no nível de implantação: uma vez definido, sessões individuais não podem escalar além dele (embora possam escolher um limite mais estrito por sessão via cabeçalho x-harness-auto-approve-risk).

Ou na configuração do seu cliente MCP:

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

Autonomia parcial: Você também pode aprovar automaticamente apenas até um nível de risco específico, ainda solicitando prompt para operações de maior risco:

# 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

Valor	O que é aprovado automaticamente
none (padrão)	Nada — nenhum limite de aprovação automática
low_write	Leituras + escritas de baixo risco
medium_write	Leituras + escritas de baixo e médio risco
high_write	Leituras + escritas de baixo, médio e alto risco
all	Tudo, incluindo operações destrutivas

Aviso sobre modo autônomo: HARNESS_AUTO_APPROVE_RISK=all pula a confirmação para todas as operações, incluindo harness_delete. Use com cautela e considere combinar com HARNESS_TOOLSETS para restringir quais tipos de recursos estão disponíveis.

Nota de migração: HARNESS_SKIP_ELICITATION=true ainda é suportado e mapeia para HARNESS_AUTO_APPROVE_RISK=all. Um aviso de depreciação é registrado em stderr. Se ambos forem definidos, HARNESS_AUTO_APPROVE_RISK tem precedência.

Segurança

• Segredos nunca são expostos. O tipo de recurso secret retorna apenas metadados (nome, tipo, escopo) — valores de segredos nunca são incluídos em nenhuma resposta.
• Operações que exigem confirmação usam elicitação quando disponível. Quando uma ação de escrita ou execução tem risco medium_write, high_write ou destructive, harness_create, harness_update, harness_delete e harness_execute tentam elicitação MCP antes de prosseguir (veja Elicitação). Ações de baixo risco (read, low_write — ex.: pipeline.create, pipeline.update, hql_query.run) prosseguem silenciosamente sem prompt.
• Risco médio e acima falham de forma fechada. Se a confirmação não puder ser obtida para operações medium_write, high_write ou destructive, elas são bloqueadas em vez de executadas cegamente. Substitua com HARNESS_AUTO_APPROVE_RISK para fluxos de trabalho autônomos.
• CORS restrito à mesma origem. O transporte HTTP permite apenas requisições de mesma origem, prevenindo ataques CSRF de sites maliciosos que miram o servidor MCP em localhost.
• Limitação de taxa HTTP. O transporte HTTP aplica 60 requisições por minuto por IP para evitar inundação de requisições.
• Limitação de taxa da API. O cliente da API Harness aplica um limite de 10 requisições por segundo para evitar atingir limites upstream.
• Limites de paginação aplicados. Consultas de lista são limitadas a 10.000 itens no total e 100 por página para evitar exaustão de memória.
• Tentativas com backoff. Falhas transitórias (HTTP 429, 5xx) são tentadas novamente com backoff exponencial e jitter.
• Vinculação a localhost. O transporte HTTP vincula-se a 127.0.0.1 por padrão — não acessível pela rede.
• Sem registro em stdout. Todos os logs vão para stderr para evitar corromper o transporte JSON-RPC stdio.

Skills Complementares

O servidor MCP Harness combina bem com Harness Skills — uma coleção de skills prontas do Claude Code (comandos de barra) projetadas para fluxos de trabalho comuns do Harness. Instale-os junto com este servidor MCP para obter automação de alto nível como /deploy, /rollback, /triage e mais sem escrever prompts personalizados.

Solução de Problemas e Armadilhas Comuns

Sintoma	Causa provável	O que fazer
HARNESS_ACCOUNT_ID is required when the API key does not include an account ID segment...	A chave de API não está em um formato compatível com escopo de conta (pat.<accountId>... ou sat.<accountId>...), então o ID da conta não pode ser inferido	Defina HARNESS_ACCOUNT_ID explicitamente
Unknown transport: "..." na inicialização	Argumento de transporte CLI não suportado	Use apenas stdio ou http
Invalid HARNESS_TOOLSETS: ... na inicialização	Um ou mais nomes de toolset não são reconhecidos	Use apenas nomes de Filtragem de Toolset (correspondência exata)
HTTP mcp-session-id header is required...	Uma solicitação de sessão foi enviada sem o cabeçalho de sessão	Envie initialize primeiro e depois inclua mcp-session-id em POST/GET/DELETE /mcp
HTTP Session not found...	A sessão expirou após MCP_SESSION_TTL_MS milissegundos de inatividade ou já foi encerrada	Execute novamente initialize para criar uma nova sessão e tente novamente com o novo cabeçalho
HTTP 405 Method Not Allowed em /mcp	Método não suportado para o endpoint MCP	Use apenas POST, GET, DELETE ou OPTIONS
HTTP Invalid request	Corpo JSON inválido ou corpo da solicitação excedeu HARNESS_MAX_BODY_SIZE_MB	Valide o tamanho/formato do payload JSON; aumente HARNESS_MAX_BODY_SIZE_MB se necessário
Unknown resource_type "..." das ferramentas	O tipo de recurso está com erro de digitação ou foi filtrado via HARNESS_TOOLSETS	Chame harness_describe (com search_term opcional) para descobrir tipos válidos
Missing required field "... for path parameter ..."	Uma chamada com escopo de projeto/org está sem identificadores	Defina HARNESS_ORG/HARNESS_PROJECT ou passe org_id/project_id por chamada de ferramenta
resource_scope "org" requires org_id... ou resource_scope "project" requires project_id...	Um recurso de múltiplos escopos foi forçado ao escopo de org/projeto sem identificadores suficientes	Passe o org_id/project_id ausente, configure HARNESS_ORG/HARNESS_PROJECT ou use resource_scope: "account" quando houver suporte
Read-only mode is enabled ... operations are not allowed	HARNESS_READ_ONLY=true bloqueia criar/atualizar/excluir/executar	Defina HARNESS_READ_ONLY=false se operações de escrita forem pretendidas
A execução do pipeline falha na pré-validação com entradas obrigatórias não resolvidas	O inputs fornecido não cobriu os placeholders de runtime obrigatórios	Obtenha runtime_input_template, forneça as chaves simples ausentes ou use input_set_ids para entradas estruturais
A forma abreviada de CI do pipeline (branch, tag, pr_number, commit_sha) não foi aplicada	inputs.build já foi fornecido, então a expansão da forma abreviada foi intencionalmente ignorada	Remova inputs.build para usar a expansão da forma abreviada ou mantenha a estrutura build completa e explícita
A execução do pipeline carregou a revisão YAML errada	A definição do pipeline está armazenada em Git e a execução não especificou o branch desejado do pipeline	Passe params.pipeline_branch na ação run; isso é mapeado para pipelineBranchName do Harness
wait: true retornou _wait.error	O gatilho do pipeline foi bem-sucedido, mas a sondagem no lado do servidor falhou	Reveja o execution_id com harness_get(resource_type="execution", ...) antes de decidir se deve executar novamente
wait: true retornou execution_timed_out: true	A execução não atingiu um status terminal antes de wait_timeout_seconds	Use o execution_id retornado para verificar novamente o status; aguarde um status terminal antes de executar harness_diagnose
Logs de execução vazios ou downloads de blob retornam 403	URLs de blob de log hospedadas pelo Harness exigem o caminho de autenticação/cliente Harness configurado, especialmente para hosts internos ou gerenciados localmente	Mantenha HARNESS_BASE_URL apontando para o host Harness de destino e use harness_get(resource_type="execution_log", ...) ou harness_diagnose(..., include_logs=true) em vez de contornar o cliente MCP
Operation declined by user / Operation cancelled by user	O usuário recusou ou cancelou o diálogo de confirmação de elicitação — autoritativo	Verifique os detalhes da operação com o usuário; confirm: true não contorna uma recusa explícita. O usuário deve aceitar o prompt
Operation blocked: the client could not surface a usable confirmation prompt	O cliente não tem suporte a elicitação, elicitInput falhou ou retornou uma aceitação degenerada	Tente novamente com confirm: true para automação não interativa ou use um cliente que suporte elicitação
body.template_yaml (or body.yaml) is required para criar/atualizar template	As APIs de template esperam um payload YAML completo	Forneça a string completa template_yaml em body; para exclusões, passe version_label para excluir uma versão (omita para excluir todas as versões)
HARNESS_BASE_URL must use HTTPS na inicialização	HARNESS_BASE_URL está definido como uma URL HTTP	Use HTTPS ou defina HARNESS_ALLOW_HTTP=true para desenvolvimento local

Licença

MIT