Harness MCP Server

Harness MCP Server 2.0

An MCP (Model Context Protocol) server that gives AI agents full access to the Harness.io platform through 11 consolidated tools and 245 resource types.

Related MCP server: OnlineCyberTools MCP (280+ filterable tools)

Why Use This MCP Server

Most MCP servers map one tool per API endpoint. For a platform as broad as Harness, that means 240+ tools — and LLMs get worse at tool selection as the count grows. Context windows fill up with schemas, and every new endpoint means new code.

This server is built differently:

• 11 tools, 245 resource types. A registry-based dispatch system routes harness_list, harness_get, harness_create, etc. to any Harness resource — pipelines, services, environments, orgs, projects, feature flags, cost data, and more. The LLM picks from 11 tools instead of hundreds.

• Full platform coverage. 41 default toolsets spanning CI/CD, GitOps, Feature Flags, Cloud Cost Management, Security Testing, Chaos Engineering, Database DevOps, Internal Developer Portal, Software Supply Chain, Infrastructure as Code Management, Release Management, Governance, Service Overrides, Knowledge Graph, and more. Opt-in Ansible coverage is available when you need inventory and playbook data.

• Multi-project workflows out of the box. Agents discover organizations and projects dynamically — no hardcoded env vars needed. Ask "show failed executions across all projects" and the agent can navigate the full account hierarchy.

• 35 prompt templates. Pre-built prompts for common workflows: build & deploy apps end-to-end, debug failed pipelines, review DORA metrics, triage vulnerabilities, optimize cloud costs, audit access control, plan feature flag rollouts, review pull requests, approve pending pipelines, and more.

• Works everywhere. Stdio transport for local clients (Claude Desktop, Cursor, Devin Desktop), HTTP transport for remote/shared deployments, Docker and Kubernetes ready.

• Zero-config start. Just provide a Harness API key. Account ID is auto-extracted from PAT and SAT tokens, org/project defaults are optional, and toolset filtering lets you expose only what you need.

• Extensible by design. Adding a new Harness resource means adding a declarative data file — no new tool registration, no schema changes, no prompt updates.

Prerequisites

Before installing or running the server, you need a Harness API key:

1. Log in to your Harness account

2. Go to My Profile → API Keys → + New API Key

3. Create a new Token under the API key — this generates a PAT or SAT in the format <prefix>.<accountId>.<tokenId>.<secret>

4. Save the token somewhere secure — you'll need it in the next step

For detailed instructions, see the Harness API Quickstart.

Quick Start

Option 0: Hosted Harness MCP

If your Harness account has the hosted MCP service enabled, clients that support remote MCP servers can connect directly to the managed endpoint instead of running the server locally.

Important: The hosted MCP service uses Harness Platform OAuth, not HARNESS_API_KEY. It must also be enabled/configured per account by Harness Support before the endpoint can be used.

See Hosted Harness MCP for configuration examples.

Option 1: npx (Recommended)

No install required — just run it:

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

Or configure the API key in your AI client (see Client Configuration below).

# 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

Note: The account ID is auto-extracted from PAT and SAT tokens (pat.<accountId>... or sat.<accountId>...), so HARNESS_ACCOUNT_ID is only needed for API keys without an embedded account segment.

Option 2: Global Install

npm install -g harness-mcp-v2

# Then run directly
harness-mcp-v2

Option 3: Build from Source

For development or customization:

git clone https://github.com/harness/mcp-server.git
cd mcp-server
pnpm install
pnpm build

# Run
pnpm start              # Stdio transport
pnpm start:http         # HTTP transport
pnpm inspect            # Test with MCP Inspector

Anthropic MCP Directory bundle

The MCPB bundle manifest lives in [mcp-directory/](mcp-directory/), and the 512×512 bundle icon is tracked at [icon.png](icon.png) in the repository root. The packaged archive contains root-level manifest.json, icon.png, server/, package.json, npm-shrinkwrap.json, and production node_modules/.

To keep the archive small, build MCPB packages from a staging directory:

pnpm prepare:mcpb

The staging directory is written to dist/mcpb/ with production dependencies installed from npm-shrinkwrap.json using npm's flat layout. The pinned official MCPB CLI validates it and creates dist/harness-mcp-server-<version>.mcpb.

Version tags matching v*.*.* publish that bundle to the corresponding GitHub Release automatically. To backfill an existing release without republishing npm, run the Release workflow manually with its release_tag input (for example, v3.2.20). The workflow checks out and builds that exact tag before replacing only its versioned MCPB asset.

CLI Usage

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

Transport defaults to stdio if not specified. Use http for remote/shared deployments.

HTTP Transport

When running in HTTP mode, the server exposes:

The HTTP transport runs in session-based mode. A new MCP session is created on initialize, the server returns an mcp-session-id header, and subsequent requests for that session must include the same header.

Operational constraints in HTTP mode:

• Set HARNESS_MCP_AUTH_TOKEN for shared or remotely reachable single-user and multi-user deployments. When set, every POST, GET, and DELETE request to /mcp must include Authorization: Bearer <token>.

• OAuth mode accepts HarnessID access tokens instead of HARNESS_MCP_AUTH_TOKEN and can bind to a non-loopback address without the unauthenticated opt-out.

• Non-loopback single-user and multi-user binds require HARNESS_MCP_AUTH_TOKEN by default. To run unauthenticated on a non-loopback interface anyway, set HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP=true explicitly.

• POST /mcp without mcp-session-id must be an initialize request.

• POST /mcp, GET /mcp, and DELETE /mcp for existing sessions require the mcp-session-id header.

• GET /mcp is used for SSE notifications (progress updates and elicitation prompts).

• Idle sessions are reaped after MCP_SESSION_TTL_MS milliseconds once no request or SSE stream is active (default 1800000, or 30 minutes).

• GET /health is the only non-MCP endpoint.

• Request body size is capped by HARNESS_MAX_BODY_SIZE_MB (default 10 MB).

• Set x-harness-pipeline-version: 0 or 1 on the initialize request to select V0 or V1 pipeline resources for that HTTP session.

• Set x-harness-auto-approve-risk: none|low_write|medium_write|high_write|all on the initialize request to choose a stricter per-session auto-approval threshold. The server caps this value at the deployment-level HARNESS_AUTO_APPROVE_RISK, so a session can reduce but not expand the configured approval ceiling.

HarnessID OAuth Mode

Set HARNESS_MCP_MODE=oauth to let remote MCP clients discover HarnessID and complete OAuth 2.1 Authorization Code with PKCE. OAuth mode is available only with HTTP transport. Production HarnessID, MCP resource, and API routing defaults are built in:

HARNESS_MCP_MODE=oauth

This defaults to the issuer https://id.harness.io/idp/realms/HarnessIDP, resource https://mcp.harness.io/mcp, OAuth client mcp-client, and Harness API base https://mcp.harness.io/cli. Override them only for QA, local development, or another Harness environment.

HARNESS_API_KEY must not be set in this mode. HARNESS_MCP_OAUTH_JWKS_URI defaults to <issuer>/protocol/openid-connect/certs, and HARNESS_ACCOUNT_ID is unnecessary because the account comes from the token.

The server publishes RFC 9728 protected-resource metadata and returns this challenge when a client has not authenticated:

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

It validates the HarnessID access token's RS256 signature, iss, expiry, and sub using the configured JWKS endpoint, and checks that the token was issued to HARNESS_MCP_OAUTH_CLIENT_ID through the azp claim. HARNESS_MCP_OAUTH_RESOURCE is the RFC 9728 protected-resource identifier used for discovery and challenges. Current HarnessID access tokens use aud: account rather than the MCP URL, so the resource is not compared with aud.

The account ID comes from the token's HARNESS_MCP_OAUTH_ACCOUNT_CLAIM claim (account_id by default), which the HarnessID organization scope populates. Each session stores the caller's access token and forwards it to the Harness API as Authorization: Bearer, so Harness RBAC and audit records reflect the logged-in user rather than a shared PAT. The session is bound to the sub and account it was created with: a later request may carry a refreshed token, but one for a different user or account is rejected.

Clients normally need only the MCP resource URL:

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

The client reads the protected-resource metadata, discovers HARNESS_MCP_OAUTH_ISSUER, and then uses that authorization server's RFC 8414 metadata. If the client does not support dynamic client registration, use the pre-registered mcp-client client ID.

See HarnessID OAuth for a self-hosted MCP server for the QA Keycloak checklist and validation commands.

Multi-User Mode

Set HARNESS_MCP_MODE=multi-user for shared HTTP deployments where each client authenticates as a different Harness user. In this mode:

• HARNESS_API_KEY must not be set in the server config — the server holds no Harness credentials.

• Each session must provide x-harness-api-key on the initialize request. x-harness-account-id is required only when the API key does not embed an account segment.

• Sessions may also provide x-harness-org and x-harness-project headers to set default scope for that session.

• The Harness API key flows through to every Harness API call for that session, so the audit trail in Harness reflects the real user.

• HARNESS_MCP_AUTH_TOKEN is independent and can still be used as an additional transport-layer gate.

# 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 controls Host-header validation for DNS-rebinding protection, and CORS limits browser origins. Neither is authentication; use HARNESS_MCP_AUTH_TOKEN or an authenticated gateway/reverse proxy for access control.

Client Configuration

Note: HARNESS_ORG and HARNESS_PROJECT are optional. They set the org ID and project ID used when not specified per tool call. Agents can discover orgs and projects dynamically using harness_list(resource_type="organization") and harness_list(resource_type="project"). The deprecated names HARNESS_DEFAULT_ORG_ID and HARNESS_DEFAULT_PROJECT_ID are still accepted for backward compatibility.

Hosted Harness MCP

Harness also supports a hosted MCP endpoint for accounts that have the managed service enabled. This is useful when you want a shared remote MCP endpoint instead of running npx harness-mcp-v2 or self-hosting the HTTP transport yourself.

Important: Hosted MCP authentication uses Harness Platform OAuth. It does not use HARNESS_API_KEY in the client config. Hosted MCP availability is configured per Harness account, so you will need to work with Harness Support to enable/configure the setting before using it.

The hosted endpoint https://mcp.harness.io/mcp is a managed service. Client-side MCP config in Claude, Cursor, or Cowork cannot override which Harness environment it routes to. For Harness0 or another private Harness SaaS environment, ask Harness Support to enable/configure hosted MCP for that environment, or run the local/self-hosted server and set HARNESS_BASE_URL to the target Harness host.

Hosted MCP example:

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

Example with both hosted and local entries:

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

Troubleshooting npx ENOENT or node: No such file or directory

This is a client process-launch failure, not a Harness authentication failure. The MCP server has not started yet, so changing HARNESS_API_KEY will not affect spawn npx ENOENT.

GUI apps (Cursor, Claude Desktop, Devin Desktop, VS Code) don't always inherit your shell's PATH, so they can fail to find npx or node after a config reload. Fix this by using absolute paths and explicitly setting PATH in the env block:

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

Find your paths with which npx and which node in a terminal, then make sure the directory containing node is included in the PATH value above. Common locations:

• Homebrew (macOS): /opt/homebrew/bin/npx

• nvm: ~/.nvm/versions/node/v20.x.x/bin/npx (run nvm which current to find the exact path)

• System Node: /usr/local/bin/npx

Claude Desktop (claude_desktop_config.json)

npx (zero install)

{
  "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 (local install)

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 (zero install)

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

node (local install)

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

Then set HARNESS_API_KEY in your environment or .env file.

Cursor (.cursor/mcp.json)

npx (zero install, recommended for local Cursor configs)

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

Run which npx in a terminal and use that full path for command; include the directory from which node at the front of PATH.

node (local install)

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

Run which harness-mcp-v2 after npm install -g harness-mcp-v2 and use that full path for command; include the directory from which node at the front of PATH.

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

npx (zero install)

{
  "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 (local install)

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

Using a local build from source?

Replace the command with the path to your built index.js:

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

MCP Gateway

The Harness MCP server is fully compatible with MCP Gateways — reverse proxies that provide centralized authentication, governance, tool routing, and observability across multiple MCP servers. Since the server implements the standard MCP protocol with both stdio and HTTP transports, it works behind any MCP-compliant gateway with no code changes.

Why use a gateway?

• Centralized credential management — no API keys in agent configs

• Governance & audit logging for all tool calls across teams

• Single endpoint for agents instead of N connections to N MCP servers

• Access control — restrict which teams can use which tools

Docker MCP Gateway

Register the server in your Docker MCP Gateway configuration:

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

Portkey

Add the Harness MCP server to your Portkey MCP Gateway for enterprise governance, cost tracking, and multi-LLM routing:

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

LiteLLM

Add to your LiteLLM proxy config:

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

Envoy AI Gateway

The server works with Envoy AI Gateway's MCP support via HTTP transport:

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

Then configure Envoy to route to http://localhost:8080/mcp as an upstream MCP backend.

Kong

Use Kong's AI MCP Proxy plugin to expose the Harness MCP server through your existing Kong gateway infrastructure.

Other Gateways

Any gateway that supports the MCP specification (Microsoft MCP Gateway, IBM ContextForge, Cloudflare Workers, etc.) can proxy this server. For stdio-based gateways, use the default transport. For HTTP-based gateways, start the server with http transport and point the gateway at the /mcp endpoint.

Docker

Build and run the server as a Docker container:

# 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

The container runs in HTTP mode on port 3000 by default with a built-in health check.

Kubernetes

Deploy to a Kubernetes cluster using the provided manifests:

# 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

The deployment runs 2 replicas with readiness/liveness probes, resource limits, and non-root security context. The Service exposes port 80 internally (targeting container port 3000).

Configuration

The server automatically loads environment variables from a .env file in the project root if one exists. Copy .env.example to .env and fill in your values. Environment variables can also be set via your shell or MCP client config.

Semantic Search

harness_search uses semantic routing to narrow scatter-gather API calls before fanning out to Harness. Three search providers are available:

Remote provider configuration:

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

Testing the remote provider locally with the included stub service (no external dependencies):

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

The stub (stub-search-service.py) implements the same /v1/health, /v1/ingest, and /v1/search contract as the production search service. It uses a simple bag-of-chars embedding so no model download is required — results are semantically plausible but not production-quality.

HTTPS Enforcement

HARNESS_BASE_URL must use HTTPS by default. If you set a non-HTTPS URL (e.g. http://localhost:8080), the server will refuse to start with:

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

Audit Logging

All registry-dispatched Harness API operations (list, get, create, update, delete, and execute) emit structured audit events when audit sinks are configured. Mutating events include the confirmation path used by elicitation or auto-approval when a confirmation context is present; read events currently omit confirmation metadata. Local metadata and schema discovery tools that bypass the registry, such as harness_describe and harness_schema, are not part of this audit stream. A stderr sink is registered by default but goes through the normal logger and obeys LOG_LEVEL; configure file or webhook sinks for durable audit collection:

• HARNESS_AUDIT_FILE appends newline-delimited JSON events for local collection.

• HARNESS_AUDIT_WEBHOOK_URL posts { "events": [...] } batches to an HTTPS webhook, optionally with HARNESS_AUDIT_WEBHOOK_TOKEN. Failed batches are re-enqueued with bounded capacity and eventually dropped with a warning rather than blocking tool execution.

• OTEL_EXPORTER_OTLP_ENDPOINT enables audit spans when the optional OpenTelemetry peer dependencies are installed. The sink reuses an existing tracer provider when one is registered, otherwise it bootstraps a standalone OTLP exporter.

Each event includes the tool name, resource type, operation, identifiers, timestamp, risk, outcome, HTTP method/path, duration, and confirmation method when applicable. Audit sinks are best-effort telemetry; delivery issues are logged and never replay or change the underlying Harness API operation. For OTel setup details and span attributes, see specs/005-otel-audit-sink.md.

Tools Reference

The server exposes 11 MCP tools. Most API tools accept org_id and project_id as optional overrides — if omitted, they fall back to HARNESS_ORG and HARNESS_PROJECT. harness_describe is local metadata only and does not use org/project scope.

URL support: Most API-facing tools accept a url parameter — paste a Harness UI URL and the server auto-extracts org, project, resource type, resource ID, pipeline ID, and execution ID. harness_describe does not accept url.

Scope support: Resource types with account/org/project variants expose supportedScopes in harness_describe. Pass resource_scope when you need a specific level:

• resource_scope: "account" sends only accountIdentifier.

• resource_scope: "org" sends accountIdentifier and orgIdentifier.

• resource_scope: "project" sends account, org, and project identifiers.

Current multi-scope resources include connector, service, environment, infrastructure, secret, file_store, template, policy, and policy_set. If resource_scope is omitted, the registry uses the resource's default scope and configured defaults, except resources marked as optional scope may omit org/project unless explicitly passed. Harness URLs can also set the scope automatically when the path contains account-level or project-level context.

Structured output: Every tool declares an MCP outputSchema. harness_list normalizes list-like Harness responses into object-shaped structured content so strict clients can validate it: top-level arrays become { "items": [...], "total": <count>, "page": <page> }, and common wrapper keys such as content, data, body, objects, or features are hoisted to items when needed. The text response still contains the compact JSON payload returned to all clients.

Schema Lookup Workflow

Use harness_schema before creating or updating YAML-backed resources so agents can copy exact field names and constraints instead of guessing from prose.

• Bundled schemas include pipeline, template, trigger, pipeline_v1, template_v1, inputSet_v1, overlayInputSet_v1, and agent-pipeline.

• Entity schemas include connector, environment, service, secret, and infrastructure. They are scope-aware (account, org, or project) and require org_id/project_id when the selected scope requires them.

• Release Management definitions (release_process, release_activity) fetch live JSON Schema from RMG /api/yamlSchema (not bundled). Pass scope, org_id, and project_id when scoping to org or project.

• Vendored entity snapshots are used first when they match the runtime account; otherwise the tool falls back to the Harness NG /yaml-schema API and caches the result.

• Omit path for a field/section summary, then pass a dot-separated path to inspect a nested definition.

Examples:

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

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

Maintainers can refresh the vendored entity snapshots with pnpm sync-entity-schemas when Harness entity YAML schemas change.

Tool Examples

Discover what resources are available:

{ "resource_type": "pipeline" }

List organizations in the account:

{ "resource_type": "organization" }

List projects in an organization:

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

List pipelines in a project:

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

Get a specific service:

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

Run a pipeline:

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

Toggle a feature flag:

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

Search across all resource types:

{ "query": "payment-service" }

Diagnose an execution by ID (summary mode — default):

{ "execution_id": "abc123XYZ" }

Diagnose from a Harness URL:

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

Diagnose connector connectivity:

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

Diagnose delegate health:

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

Diagnose a GitOps application (with options):

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

Get the latest execution report for a pipeline:

{ "pipeline_id": "my-pipeline" }

Full diagnostic mode with YAML and failed step logs:

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

Summary mode with logs enabled (best of both):

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

Get project health status:

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

List database schemas filtered by migration type:

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

List database instances for a schema:

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

Get the resolved LLM authoring pipeline for a schema and instance:

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

List snapshot object names (e.g. tables) for a schema instance:

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

Get full snapshot metadata for specific named objects:

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

Pipeline Run Workflow (Recommended)

For v0 pipelines, use this sequence to reduce execution-time input errors:

1. Discover required runtime inputs

• harness_get(resource_type="runtime_input_template", resource_id="<pipeline_id>")

• The returned template shows <+input> placeholders that need values.

2. Choose input strategy

• Simple variables: pass flat key-value inputs (for example {"branch":"main","env":"prod"}).

• Complex/structural inputs: use input_set_ids (CI codebase/build blocks and nested template inputs are best handled this way).

• CI codebase shorthand keys (pipeline run only):

  Shorthand key	Expanded structure
  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>

• Constraint: shorthand expansion is skipped when inputs.build is already present (explicit build wins).

3. Execute the run

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

• For Git-backed pipelines whose YAML should be loaded from a non-default branch, pass params.pipeline_branch (sent to Harness as pipelineBranchName):

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

4. Optional: combine both

• Use input_set_ids for the base shape and inputs for simple overrides.

For v1 pipelines:

1. Fetch harness_get(resource_type="runtime_input_template_v1", resource_id="<pipeline_id>"). For Git-backed pipelines, pass branch_name, connector_ref, and repo_name through params.

2. Use each returned inputs[].details.name as a top-level key in harness_execute.inputs.

3. Run harness_execute(resource_type="pipeline_v1", action="run", resource_id="<pipeline_id>", inputs={...}). The server wraps these values under an inputs: YAML root and sends the API's inputs_yaml body.

If required fields are unresolved, the tool returns a pre-flight error with expected keys and suggested input sets. You can inspect available shorthand mappings with harness_describe(resource_type="pipeline") (executeActions.run.inputShorthands).

Dynamic Pipeline Execution

Use pipeline_dynamic_execution.run when an agent or external system generates the full v0 pipeline YAML at runtime and needs to run it against an existing Harness pipeline shell. This is not a replacement for normal pipeline.run: the saved v0 pipeline must already exist, account-level and pipeline-level Allow Dynamic Execution must be enabled, and the caller needs Edit plus Execute permissions on the 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
  }
}

Constraints:

• body must be an object with a yaml field. Raw string bodies are rejected by the public harness_execute schema.

• body.yaml may be a YAML string or a JSON pipeline object; JSON is serialized to YAML before the request.

• Runtime <+input> placeholders are not resolved by this API. Submit fully resolved YAML.

• Input sets, selective stage execution, retry, and triggers are not supported by the dynamic execution endpoint.

• The action is high_write and uses the normal confirmation/auto-approval path. The response projects the API envelope to { "execution_id": "...", "status": "..." } and includes an openInHarness execution link when scope data is available.

If Harness rejects the run as not enabled, check both the account-level Allow Dynamic Execution setting and the pipeline-level toggle under Pipeline -> Advanced Options -> Dynamic Execution Settings.

Execution Input Forensics

Use execution_inputs after a run to inspect the merged input YAML that produced a specific execution. This is useful when a failure depends on input-set merging, Git-backed input set branches, or trigger/runtime values that are hard to reconstruct from the execution page alone.

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

The get response is projected to:

• executionId - the plan execution ID from resource_id.

• inputSetYaml - merged runtime input YAML used for the run, or null.

• inputSetTemplateYaml - input template at execution time, or null.

• resolvedYaml - expression-resolved YAML when resolve_expressions=true, otherwise usually null.

• inputSetDetails - contributing saved input sets as { identifier, name } pairs.

• inputSetBranchName - source branch for Git-backed input sets, or null.

execution_inputs is get-only and read-risk. If resolve_expressions is omitted, the server omits the API query parameters and Harness uses its default UNKNOWN resolution mode.

Pipeline Execute Wait Mode

For pipeline.run, pipeline.retry, and pipeline_v1.run, pass wait: true to let the server poll until the execution reaches a terminal status. This keeps a pipeline launch and status check in one tool call instead of asking the client or LLM to run a polling loop.

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

Wait mode behavior:

• Default timeout is 600 seconds; allowed range is 10 seconds to 7200 seconds.

• Initial poll interval defaults to 3 seconds, backs off by 1.5x, and caps at 30 seconds.

• On success or failure, the response includes fields such as execution_id, execution_status, execution_terminal, execution_elapsed_ms, and execution_poll_count.

• If the timeout fires, the original trigger still succeeded; the response includes execution_timed_out: true and _wait.hint with the last observed status.

• If polling fails after the trigger succeeds, the response includes _wait.error and a recheck hint. Do not blindly rerun the pipeline unless you have confirmed the first execution is not running.

• Failed terminal statuses include _diagnose_hint pointing to harness_diagnose(resource_type="execution", options={execution_id: "..."}).

Ask the AI DevOps Agent to create a pipeline:

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

Update a service via natural language:

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

Pipeline Storage Modes

Harness pipelines can be stored in three ways:

Create an inline pipeline (default):

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

Create a remote pipeline (External Git — e.g. 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"
  }
}

Create a remote pipeline (Harness Code — no connector needed):

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

Update a remote pipeline:

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

Import a pipeline from an external Git repo:

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

Import a pipeline from a Harness Code repo:

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

Create a connector:

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

Delete a trigger:

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

List input sets for a pipeline:

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

Get a specific input set:

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

Create an input set:

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

Update an input set:

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

Delete an input set:

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

Resource Types

245 resource types organized across 41 toolsets. Each resource type supports a subset of CRUD operations and optional execute actions.

Platform

Pipelines

Both pipeline YAML resource types are available when the pipelines toolset is enabled. HARNESS_PIPELINE_VERSION and the HTTP x-harness-pipeline-version initialization header select the default version preference; they do not hide the other version.

AI Agents

Services

Environments

Connectors

Infrastructure

Secrets

Execution Logs

Audit Trail

Delegates

Code Repositories

commit creation commits one or more file actions directly through the Harness Code API without cloning. Pass body.title, body.branch, and body.actions; each action is CREATE, UPDATE, DELETE, or MOVE, and UPDATE requires the current blob SHA.

Artifact Registries

File Store

file_store manages Harness File Store files and folders through the generic tools. It supports account, org, and project scope; pass resource_scope="account"|"org"|"project" or paste a Harness File Store URL so the server can derive scope and IDs.

Common calls:

# List the account-level File Store.
harness_list(resource_type="file_store", resource_scope="account")

# Create a folder at the current scope root.
harness_create(resource_type="file_store", body={
  name: "scripts",
  type: "FOLDER",
  parent_identifier: "Root"
})

# Upload a UTF-8 script file. Use content_base64 instead for binary data.
harness_create(resource_type="file_store", body={
  name: "deploy.sh",
  type: "FILE",
  parent_identifier: "Root",
  content: "#!/usr/bin/env bash\n./deploy",
  mime_type: "text/x-shellscript",
  file_usage: "SCRIPT"
})

# Rename metadata without replacing file content.
harness_update(resource_type="file_store", resource_id="deploy_script", body={
  name: "deploy-prod.sh",
  type: "FILE",
  parent_identifier: "Root"
})

# List first-level children of a folder. This is a read-risk execute action.
harness_execute(resource_type="file_store", action="list_children",
  resource_id="scripts_folder", params={folder_name: "scripts"})

Multipart body constraints:

• Create/update accept JSON body, then convert it to multipart/form-data for /ng/api/file-store.

• name, type (FILE or FOLDER), and parent_identifier are required; use the literal "Root" only for the root of the selected scope.

• FILE create requires exactly one of content (UTF-8 string) or content_base64 (valid non-empty base64). FILE update can omit content for metadata-only updates, or provide exactly one content field to replace content.

• FOLDER create/update must omit content and content_base64.

• Optional file_usage must be MANIFEST_FILE, CONFIG, or SCRIPT; optional scalar metadata such as description, mime_type, path, and tags must be strings.

• Upload content is capped at 100 MB. Confirmation prompts redact content, content_base64, and contentBase64 previews before elicitation.

list_children accepts either shorthand (resource_id plus params.folder_name, or params.file_store_id/params.folder_identifier plus params.folder_name) or a full FileStoreNode body with identifier, name, and type: "FOLDER". Full bodies use Harness camelCase parentIdentifier; shorthand may use params.parent_identifier.

Templates

Template operations use the Harness Template service paths (/template/api/templates...). Create and update require the full template YAML string in body.template_yaml or body.yaml; version_label targets a specific version for update/delete, while deleting without version_label deletes all versions.

Dashboards

Database DevOps

Infrastructure as Code Management (IaCM)

IaCM resources are default-enabled and mostly project-scoped. Start with iacm_workspace to find workspace identifiers, then use that workspace_id for workspace resources, costs, and activity diffs. Use iacm_variable_set for reusable variable sets at account, org, or project scope. The provider registry is account-scoped.

iacm_module spans account, org, and project scope. It defaults to the account registry; every operation (list, get, create, update) sends the same scope_org / scope_project query params, so a module you create is discoverable at the scope you created it. Select the scope with resource_scope="account" | "org" | "project" plus org_id/project_id. Scoping is opt-in: when resource_scope is omitted, org_id/project_id apply only if you pass them explicitly — configured HARNESS_ORG/HARNESS_PROJECT defaults are not applied, so an ambient project config cannot silently register an account module under a project. A module body's own org/project fields locate its Git connector and are unrelated to this visibility scope.

iacm_workspace create/update return { policy_evaluation } only — follow up with harness_get to fetch the workspace. iacm_variable_set and iacm_module create/update return the resource itself. iacm_provider create returns { id } only — follow up with harness_get; update is version-oriented only (POST/PUT /providers/{id}/version) — there is no metadata PUT. Version writes may return an empty body; HarnessClient normalizes that to { status: "SUCCESS", message: "No content" }.

Variable-set update is HTTP PUT with full-replacement collections — always harness_get first, then PUT the full desired body (terraform_variables / environment_variables are required on update; omit/empty clears connectors and variable files). Module update is also PUT — prefer get-then-put for optional fields. Writes are medium_write and require confirmation (elicitation or confirm: true).

Variable-set and provider-registry RBAC (iac_variableset_*, iac_providerregistry_*) are currently Experimental in Harness — access checks always allow until iac-server activates enforcement. Module registry RBAC (iac_registry_view / iac_registry_edit) is Active and enforceable. MCP always forwards the caller PAT/SAT unchanged.

Typical workflow:

1. harness_list(resource_type="iacm_workspace", org_id="...", project_id="...") to find the workspace.

2. harness_create / harness_update on iacm_workspace to create from scratch or a template (associated_template), or update an existing workspace — response is { policy_evaluation } only.

3. harness_get(resource_type="iacm_workspace", workspace_id="...") to fetch the created/updated workspace.

4. harness_list / harness_create / harness_update on iacm_variable_set (optionally with resource_scope) for reusable Terraform/env variable sets — response is the VariableSet resource.

5. harness_list / harness_create / harness_update on iacm_module for the module registry (name + system required; add resource_scope with org_id/project_id for an org- or project-scoped module) — response is the module resource.

6. harness_list / harness_create / harness_update on iacm_provider for the account provider registry (body.type required for create; create returns { id } only — then harness_get; update creates/updates versions only) — version update may return empty success.

7. harness_list(resource_type="iacm_resource", org_id="...", project_id="...", workspace_id="...") to inspect Terraform resources, outputs, and data sources.

8. harness_list(resource_type="iacm_workspace_costs", org_id="...", project_id="...", workspace_id="...") to review per-execution cost entries.

9. harness_list(resource_type="iacm_activity_resource_change", org_id="...", project_id="...", activity_id="...", workspace_id="...") to inspect before/after resource diffs for a plan, apply, or destroy activity.

IaCM list responses expose page_count as the count for the current page only (except iacm_variable_set, which is not paginated). When has_more is true, keep requesting the next 1-based page and sum page counts if you need a total.

Internal Developer Portal (IDP)

Pull Requests

Use harness_execute(resource_type="pull_request", action="close", ...) for an explicit close operation. harness_update also accepts body.state (open or closed) and routes state changes to the dedicated Harness Code PR state endpoint; send title/description edits in a separate update call.

Release Management

Release Management (RMG) resources are default-enabled. Definition resources (release_process, release_activity) support list/get/create/update/delete with body.yaml; call harness_schema(resource_type="release_process"|"release_activity") before create/update. Execution resources monitor running releases — most list operations require release_id (UUID from harness_list resource_type=release, or the UI URL slug such as identifier-1.0.0-abc). Paste an RMG release URL into harness_list to auto-fill release_id.

RMG calls use ${HARNESS_BASE_URL}/gateway/rmg with account scoping via the Harness-Account header. Org/project scope uses header-based scoping when org_id/project_id are provided. release_execution_phase is list-only — use each phase item's identifier field as params.phase_identifier when calling harness_get on phase input/output resources (do not call harness_get on release_execution_phase itself). Release list status filtering is applied client-side on the current page only; keep paging with the same filters when results may span pages.

Typical workflow:

1. harness_list(resource_type="release_process", org_id="...", project_id="...") to discover orchestration process definitions.

2. harness_schema(resource_type="release_process") (or release_activity) before create/update; then harness_create / harness_update with body.yaml.

3. harness_list(resource_type="release", org_id="...", project_id="...") to find active or recent releases (default 30-day look-back; optional filters.status, filters.search_term, filters.days_back).

4. harness_get(resource_type="release", release_id="...") for release details.

5. harness_list(resource_type="release_execution_phase", filters={ release_id: "..." }) for phase status; same release_id for release_execution_task and release_execution_activity.

6. harness_get on release_input, release_execution_phase_input, release_execution_phase_output, release_execution_activity_output, or release_execution_activity_input using release_id plus params.phase_identifier / params.activity_identifier / activity_execution_id as documented on each resource.

Vibe

The default-enabled vibe toolset covers the Vibe Orchestrator BFF contract under ${HARNESS_BASE_URL}/vibe/v1. It uses the existing Harness connection and account header, without adding account/org/project query parameters or scope fields to request bodies. The team validated the Vibe flow using Harness API-key authentication (PAT/SAT), so no opt-in setting is required for default sessions. The curated OpenAPI documents bearer/session authentication; the server's OAuth mode forwards the current session's bearer token. Automated regressions verify both header paths; gateway authentication remains subject to the target environment's configuration.

The API supports two intake paths. Keep these API-native request shapes:

When packaging a directory, include the source, manifests, lockfiles, configuration, and intended uncommitted edits needed to build it. Exclude credentials, .git, installed dependencies, and generated artifacts. Packaging and the signed upload happen where the files are accessible; a hosted MCP server cannot read the coding agent's local directory.

For an existing ZIP, prepare the upload:

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

Pass this to harness_execute. The size must describe the actual ZIP; size_bytes, content_type, and md5 are optional and nullable. Additional prepare fields are preserved for backend validation, as permitted by the OpenAPI. Preparation returns projectId, sourceId, and upload, including each file's uploadUrl, method, headers, and expiresAt. Upload the file bytes directly using that signed URL, method, and headers; preserve the URL exactly and do not add Harness credentials to the storage request. The prepare action does not read or upload local files.

After a successful upload, explicitly deploy:

{
  "resource_type": "vibe_project",
  "action": "deploy",
  "resource_id": "<projectId returned by prepare>"
}

For JSON imports, use the returned id instead. Deployment also accepts body: {"project_id": "<Vibe app id>"} or params.app_id; the API wire field is snake_case project_id even though prepare returns camelCase projectId. The generic tool's top-level project_id is a Harness scope identifier and is never used as the Vibe app id. Import and prepare create the app/source; neither starts deployment. Writes are not automatically retried, and deployment uses the existing high-risk confirmation policy.

Read progress with harness_get(resource_type="vibe_app_lifecycle", resource_id="<Vibe app id>"). It retains app URLs, execution stages, substeps, failures, log lines, and build-analyzer details. The events execute action accepts resource_id or params.app_id and consumes the SSE endpoint as a finite batch: up to 20 JSON events or five seconds after connection, with a 1 MiB response limit. These limits belong to the Vibe endpoint. The connection's HARNESS_API_TIMEOUT_MS also bounds connection and stream consumption together; expiration returns a timeout error. A completed batch returns events and stop_reason (end, event_limit, or duration_limit) and closes the stream. Neither initial connection failures nor broken streams are retried. Events are transient diffs with no documented replay cursor; use lifecycle get for an authoritative snapshot. Both lifecycle reads are available in read-only mode.

Feature Flags

FME (Split.io) resources — fme_* resources support dual-mode scoping: legacy calls pass workspace_id and hit the Split.io API (api.split.io); newer calls pass org_id+project_id together and hit Harness-native endpoints (standard HARNESS_API_KEY/HARNESS_BASE_URL, same auth as every other harness_* resource) instead. Passing both workspace_id and org_id/project_id on the same call, or mixing org_id with project_id alone, is an error — pick one mode per call. Every operation below is available in legacy mode, unchanged. Harness-native mode coverage is currently narrower:

• fme_workspace — no Harness-native equivalent; legacy-only (used to discover workspace_id values).

• fme_environment — dual-mode list (workspace_id or org_id+project_id). get/create/update/delete are Harness-native only (/fme/api/v4/environments) — MCP never had a workspace_id contract for those ops. Native list uses optional offset/limit (max 100; harness_list size maps to limit); envelope {data, limit, offset, totalCount} is promoted to items/total. Native create/update use isProduction (production accepted as an alias). Native update is JSON Merge Patch; name and isProduction are not clearable. Name max 15 characters.

• fme_feature_flag — dual-mode, both branches fully wired. Harness-native (org_id+project_id): list/get/create/delete hit /fme/api/v4/feature-flags (body for create: name, trafficType, optional description/tags/owners, per CreateFeatureFlagRequest); update sends a merge-patch to /fme/api/v4/feature-flags/{name}; archive/unarchive hit /fme/api/v4/feature-flags/{name}/archive|unarchive (optional comment only — no title, per ArchiveUnarchiveRequest); kill/restore/reallocate hit /fme/api/v4/feature-flag-definitions/{name}/kill|restore|reallocate with environment_id as a query param (optional comment/title, per FeatureFlagDefinitionActionRequest).

• fme_feature_flag_definition — get/create/update remain dual-mode (workspace_id or org_id+project_id). list/delete/kill/restore/reallocate are Harness-native only (org_id+project_id) — MCP never had a workspace_id contract for those ops. Native list requires feature_flag_name and uses offset/limit (default 100, max 100); it does not take environment_id. Delete and execute require environment_id. Kill/restore/reallocate are the same actions as on fme_feature_flag. Get/create/update body matches legacy (treatments, defaultTreatment, defaultRule, optional rules/baselineTreatment/trafficAllocation/comment), plus optional title in Harness-native mode. Native update is JSON Merge Patch.

• fme_rollout_status — dual-mode list. Pass org_id+project_id (preferred) or the deprecated workspace_id. Native pagination uses offset/limit (max 100; harness_list size maps to limit); results are promoted to items/total. Each item has id, name, and optional description.

• fme_rule_based_segment — (Deprecated — see fme_segment.) Harness-native mode is rejected on every operation (list/get/create/delete) — use fme_segment instead; this resource supports only the legacy workspace_id contract.

• fme_rule_based_segment_definition — (Deprecated — see fme_segment_definition.) Harness-native mode is rejected on every operation/action (list/update/enable/disable/change_request) — use fme_segment_definition instead (no enable/disable/change_request equivalent there); this resource supports only the legacy workspace_id/environment_id contract.

• fme_traffic_type — dual-mode list. Pass org_id+project_id (preferred) or the deprecated workspace_id. Native pagination uses offset/limit (max 100; harness_list size maps to limit); results are promoted to items/total. Each item has id and name (no displayAttributeId).

• fme_identity — create/update are not yet implemented if org_id+project_id are passed together; otherwise proceeds as a normal legacy call.

• fme_standard_segment — deprecated. Legacy workspace_id still hits Split v2. Harness-native is rejected — use fme_segment.

• fme_segment_keys — list/update remain legacy (workspace_id / environment_id+segment_name). Harness-native (org_id+project_id) is rejected — use fme_segment_definition execute list_keys/add_keys/remove_keys.

• fme_segment — Native only (org_id+project_id). CRUD. list/get/update/delete require segment_type: STANDARD | LARGE | RULE_BASED. Create body: name, trafficType, segmentType; optional description, tags, owners.

• fme_segment_definition — Native only. CRUD plus execute list_keys/add_keys/remove_keys. Update is description only. Delete fails with hasDependents while keys remain.

In single-user/self-hosted mode, legacy-mode auth uses a Bearer token from HARNESS_FME_API_KEY, falling back to a non-placeholder HARNESS_API_KEY. HARNESS_FME_API_KEY may be a legacy Split admin key or an FME-entitled Harness PAT/SAT, but it is rejected in multi-user mode so shared deployments cannot override each session user's credential. Hosted OAuth/service-routing credentials for Harness platform APIs do not authenticate direct Split.io requests. fme_feature_flag supports full lifecycle management in legacy mode: create (requires traffic_type_id), list, get, update metadata, delete, and kill/restore/reallocate/archive/unarchive execute actions. Use fme_traffic_type to discover traffic type IDs, fme_identity to create/update identity attributes, and fme_standard_segment / fme_segment_keys to inspect standard segments and add member keys. fme_rule_based_segment provides CRUD for targeting segments, while fme_rule_based_segment_definition manages environment-specific segment rules with enable/disable and change request approval flows.

GitOps

Chaos Engineering

Cloud Cost Management (CCM)

Software Engineering Insights (SEI)

SEI resources are consolidated for token efficiency. Use metric or aspect params for DORA, team/org-tree details, and AI insights.

Software Supply Chain Assurance (SCS)

Evidence Vault

Evidence Vault stores in-toto attestations (SDLC evidences). List supports account/org/project scope via resource_scope. Singular free-text filters (pipeline, artifact alone, gitoid) use search_term; an additional Name constraint uses filters.subject_name; subject content digest uses filters.subject_digest. Get looks up by gitoid_sha256 and requires org_id/project_id (from the list row). Download (harness_execute action download) returns a time-limited download_url — always show that link to the user. Requires feature flag SCS_EVIDENCE_VAULT.

Security Testing Orchestration (STO)

security_exemption create is a high_write operation. The server derives requester_id from the authenticated PAT, sets exemptFutureOccurrences=true, and defaults duration_days to 30 when not provided. For listing exemptions, pass a small explicit page size (for example filters: { "status": "Pending", "size": 5 }) and follow the _nextPageHint returned in each response.

Security exemption execute workflow:

• Use harness_list with resource_type="security_exemption" and an explicit status such as Pending, Approved, Rejected, Expired, or Canceled.

• Use harness_execute with action="approve" and a required body.scope: CURRENT, ACCOUNT, ORG, or PROJECT. CURRENT approves at the exemption's existing scope; the other scopes use the STO promote endpoint internally. The server auto-fills body.approver_id from the authenticated user when omitted; body.comment is optional.

• Use action="reject" to reject an exemption. body.approver_id is also auto-filled when omitted.

• There is no separate promote execute action. Use action="approve" with a non-CURRENT body.scope when the requested outcome is approval at account, organization, or project scope.

Access Control

Governance

Deployment Freeze

Service Overrides

Settings

MCP Prompts

DevOps

FinOps

DevSecOps

Harness Code

MCP Resources

Toolset Filtering

By default, 41 of 44 toolsets are enabled. Three toolsets are opt-in and excluded from the defaults:

• ansible — Harness Ansible (inventories, playbooks, hosts, activity). Opt-in because it is project-scoped and adds concepts many users do not need.

• autonomous_work — Development Harness (autonomous work). Opt-in; see toolset description for scope.

• registries-v3 — Harness Artifact Registry v3 (packages, versions, files, metadata, scans, firewall exceptions). Opt-in until v3 writes land, so agents don't have to disambiguate between v1 registries/artifacts and v3 packages/versions.

Adding toolsets with + prefix

Use the + prefix to explicitly include opt-in toolsets alongside all defaults:

# Explicitly include Ansible alongside all defaults
HARNESS_TOOLSETS=+ansible

Removing default toolsets

Use the - prefix to exclude toolsets you don't need:

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

Combining + and -

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

Explicit allowlist

An explicit comma-separated list (no prefixes) replaces the defaults entirely. Only the listed toolsets are enabled:

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

Available toolset names:

Architecture

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

How It Works

1. Tools are generic verbs: harness_list, harness_get, etc. They accept a resource_type parameter that routes to the correct API endpoint.

2. The Registry maps each resource_type to a ResourceDefinition — a declarative data structure specifying the HTTP method, URL path, path/query parameter mappings, and response extraction logic.

3. Dispatch resolves the resource definition, builds the HTTP request (path substitution, query params, resource_scope-aware account/org/project injection), calls the Harness API through HarnessClient, and extracts the relevant response data.

4. Toolset filtering (HARNESS_TOOLSETS) controls which resource definitions are loaded into the registry at startup.

5. Structured output is declared with MCP outputSchema; harness_list coerces arrays and common list wrappers into object-shaped structuredContent for strict clients.

6. Deep links are automatically appended to responses, providing direct Harness UI URLs for every resource.

7. Compact mode strips verbose metadata from list results, keeping only actionable fields (identity, status, type, timestamps, deep links) to minimize token usage.

Adding a New Resource Type

Create a new file in src/registry/toolsets/ or add a resource to an existing toolset:

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

Then import it in src/registry/index.ts and add it to the ALL_TOOLSETS array. No changes needed to any tool files.

Development

# 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

Project Structure

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

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

Elicitation

The write tools (harness_create, harness_update, harness_delete, harness_execute) use MCP elicitation to prompt the user for confirmation when the action's risk requires it — medium_write, high_write, and destructive operations only. Low-risk creates / updates / reads (e.g. pipeline.create, pipeline.update, hql_query.run) proceed silently with no prompt. When a prompt is surfaced, the user sees what's about to happen and accepts or declines, giving real human-in-the-loop approval for the operations that actually mutate or run things.

How it works:

1. The LLM calls a write tool with medium_write+ risk (e.g. harness_delete, harness_execute pipeline.run). Low-risk creates / updates / reads do not surface a prompt.

2. The server sends an elicitation request to the client with a summary of the operation and a confirm checkbox (default checked).

3. The user sees the details and clicks Accept (with confirm checked) or Decline / Cancel.

4. If accepted with confirm: true, the operation proceeds. If accepted with confirm unchecked, declined, or cancelled, it's blocked and the LLM is told (an explicit decline is authoritative and not bypassed by confirm: true on the tool call).

Client support:

Elicitation behavior varies by operation risk when client support is missing:

If elicitInput fails at runtime (transport error, unsupported method) for a medium_write+ operation, the call is blocked unless the caller passes confirm: true. confirm: true is honored as a fallback when the client could not surface a prompt or returned a degenerate accept ({action: "accept"} without the confirm field), but it does not override an explicit decline/cancel from a client that completed the elicitation handshake.

Autonomous Mode

Autonomous mode means the server proceeds with all operations — including writes and destructive actions — without prompting for confirmation. Enable it by setting:

HARNESS_AUTO_APPROVE_RISK=all

This is the deployment-level ceiling: once set, individual sessions cannot escalate beyond it (though they can choose a stricter threshold per-session via the x-harness-auto-approve-risk header).

Or in your MCP client config:

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

Partial autonomy: You can also auto-approve only up to a specific risk level while still prompting for higher-risk operations:

# 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

Autonomous mode warning: HARNESS_AUTO_APPROVE_RISK=all skips confirmation for all operations including harness_delete. Use with caution and consider pairing with HARNESS_TOOLSETS to restrict which resource types are available.

Migration note: HARNESS_SKIP_ELICITATION=true is still supported and maps to HARNESS_AUTO_APPROVE_RISK=all. A deprecation warning is logged to stderr. If both are set, HARNESS_AUTO_APPROVE_RISK takes precedence.

Safety

• Secrets are never exposed. The secret resource type returns metadata only (name, type, scope) — secret values are never included in any response.

• Confirmation-requiring operations use elicitation when available. When a write or execute action has medium_write, high_write, or destructive risk, harness_create, harness_update, harness_delete, and harness_execute attempt MCP elicitation before proceeding (see Elicitation). Low-risk actions (read, low_write — e.g. pipeline.create, pipeline.update, hql_query.run) proceed silently with no prompt.

• Medium-risk and above fail closed. If confirmation cannot be obtained for medium_write, high_write, or destructive operations, they are blocked instead of executing blindly. Override with HARNESS_AUTO_APPROVE_RISK for autonomous workflows.

• CORS restricted to same-origin. The HTTP transport only allows same-origin requests, preventing CSRF attacks from malicious websites targeting the MCP server on localhost.

• HTTP rate limiting. The HTTP transport enforces 60 requests per minute per IP to prevent request flooding.

• API rate limiting. The Harness API client enforces a 10 requests/second limit to avoid hitting upstream rate limits.

• Pagination bounds enforced. List queries are capped at 10,000 items total and 100 per page to prevent memory exhaustion.

• Retries with backoff. Transient failures (HTTP 429, 5xx) are retried with exponential backoff and jitter.

• Localhost binding. The HTTP transport binds to 127.0.0.1 by default — not accessible from the network.

• No stdout logging. All logs go to stderr to avoid corrupting the stdio JSON-RPC transport.

Complementary Skills

The Harness MCP server pairs well with Harness Skills — a collection of ready-made Claude Code skills (slash commands) designed for common Harness workflows. Install them alongside this MCP server to get high-level automation like /deploy, /rollback, /triage, and more without writing custom prompts.

Troubleshooting & Common Pitfalls

License

MIT