Harness

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

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.

- 11 tools, 240 resource types.A registry-based dispatch system routesharness_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.39 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.
- 34 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.

Before installing or running the server, you need a Harness API key:
- Log in to yourHarness account
- Go toMy Profile→API Keys→+ New API Key
- Create a newTokenunder the API key — this generates a PAT or SAT in the format<prefix>.<accountId>.<tokenId>.<secret>
- Save the token somewhere secure — you'll need it in the next step

For detailed instructions, see theHarness API Quickstart.

SeeHosted Harness MCPfor configuration examples.

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

Or configure the API key in your AI client (seeClient Configurationbelow).

# 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

npm install -g harness-mcp-v2 # Then run directly harness-mcp-v2

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

The MCPB bundle manifest lives inmcp-directory/, and the 512×512 bundle icon is tracked aticon.pngin the repository root. The packaged archive contains root-levelmanifest.json,icon.png,server/,package.json,npm-shrinkwrap.json, and productionnode_modules/.

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

The staging directory is written todist/mcpb/with production dependencies installed fromnpm-shrinkwrap.jsonusing npm's flat layout. The pinned official MCPB CLI validates it and createsdist/harness-mcp-server-<version>.mcpb.

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

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 tostdioif not specified. Usehttpfor remote/shared deployments.

When running in HTTP mode, the server exposes:

The HTTP transport runs insession-based mode. A new MCP session is created oninitialize, the server returns anmcp-session-idheader, and subsequent requests for that session must include the same header.

- SetHARNESS_MCP_AUTH_TOKENfor any shared or remotely reachable deployment. When set, everyPOST,GET, andDELETErequest to/mcpmust includeAuthorization: Bearer <token>.
- Non-loopback binds requireHARNESS_MCP_AUTH_TOKENby default. To run unauthenticated on a non-loopback interface anyway, setHARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP=trueexplicitly.
- POST /mcpwithoutmcp-session-idmust be aninitializerequest.
- POST /mcp,GET /mcp, andDELETE /mcpfor existing sessions require themcp-session-idheader.
- GET /mcpis used for SSE notifications (progress updates and elicitation prompts).
- Idle sessions are reaped afterMCP_SESSION_TTL_MSmilliseconds once no request or SSE stream is active (default1800000, or 30 minutes).
- GET /healthis the only non-MCP endpoint.
- Request body size is capped byHARNESS_MAX_BODY_SIZE_MB(default10MB).
- Setx-harness-pipeline-version: 0or1on theinitializerequest to select V0 or V1 pipeline resources for that HTTP session.
- Setx-harness-auto-approve-risk: none|low_write|medium_write|high_write|allon theinitializerequest to choose a stricter per-session auto-approval threshold. The server caps this value at the deployment-levelHARNESS_AUTO_APPROVE_RISK, so a session can reduce but not expand the configured approval ceiling.

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

- HARNESS_API_KEYmustnotbe set in the server config — the server holds no Harness credentials.
- Each session must providex-harness-api-keyon theinitializerequest.x-harness-account-idis required only when the API key does not embed an account segment.
- Sessions may also providex-harness-organdx-harness-projectheaders 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_TOKENis 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_HOSTScontrols Host-header validation for DNS-rebinding protection, and CORS limits browser origins. Neither is authentication; useHARNESS_MCP_AUTH_TOKENor an authenticated gateway/reverse proxy for access control.

Note:HARNESS_ORGandHARNESS_PROJECTare optional. They set the org ID and project ID used when not specified per tool call. Agents can discover orgs and projects dynamically usingharness_list(resource_type="organization")andharness_list(resource_type="project"). The deprecated namesHARNESS_DEFAULT_ORG_IDandHARNESS_DEFAULT_PROJECT_IDare still accepted for backward compatibility.

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 runningnpx harness-mcp-v2or self-hosting the HTTP transport yourself.

Important:Hosted MCP authentication usesHarness Platform OAuth. It doesnotuseHARNESS_API_KEYin the client config. Hosted MCP availability is configured per Harness account, so you will need to work withHarness Supportto enable/configure the setting before using it.

The hosted endpointhttps://mcp.harness.io/mcpis 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 setHARNESS_BASE_URLto the target Harness host.

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

Troubleshootingnpx ENOENTornode: 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 changingHARNESS_API_KEYwill not affectspawn npx ENOENT.

GUI apps (Cursor, Claude Desktop, Devin Desktop, VS Code) don't always inherit your shell'sPATH, so they can fail to findnpxornodeafter a config reload. Fix this by using absolute paths and explicitly settingPATHin theenvblock:

{ "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 withwhich npxandwhich nodein a terminal, then make sure the directory containingnodeis included in thePATHvalue above. Common locations:

- Homebrew (macOS):/opt/homebrew/bin/npx
- nvm:~/.nvm/versions/node/v20.x.x/bin/npx(runnvm which currentto find the exact path)
- System Node:/usr/local/bin/npx

Claude Desktop (claude_desktop_config.json)

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

{ "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 mcp add harness -- npx harness-mcp-v2

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

Then setHARNESS_API_KEYin your environment or.envfile.

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

Runwhich npxin a terminal and use that full path forcommand; include the directory fromwhich nodeat the front ofPATH.

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

Runwhich harness-mcp-v2afternpm install -g harness-mcp-v2and use that full path forcommand; include the directory fromwhich nodeat the front ofPATH.

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

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

Replace the command with the path to your builtindex.js:

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

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.

- 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

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

Add the Harness MCP server to yourPortkey MCP Gatewayfor enterprise governance, cost tracking, and multi-LLM routing:

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

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

The server works withEnvoy AI Gateway's MCP supportvia HTTP transport:

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

UseKong's AI MCP Proxy pluginto expose the Harness MCP server through your existing Kong gateway infrastructure.

# 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

# 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

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

# 1. Create a venv and install FastAPI python3 -m venv .venv-stub .venv-stub/bin/pip install fastapi uvicorn # 2. Start the stub (in-memory, cosine similarity, corpus + tenant filtering) .venv-stub/bin/uvicorn stub-search-service:app --port 8082 # 3. Build the MCP server pnpm build # 4. Run the integration smoke test node test-remote-provider.mjs # Expected output: # available: true # indexed 2 docs # entity search results: pipeline:ts-test score=... corpus=entities # knowledge search results: schema:trigger score=... # all-corpus search results: (merged, sorted by score) # isolation check (other-acct, should be empty): PASS # 5. Tear down kill $(lsof -ti :8082)