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 218 resource types.

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, 218 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. 38 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, Governance, Service Overrides, Knowledge Graph, Visualizations, 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.
• 32 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 ...
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](#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](#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.... or sat....), 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 bundle icon is tracked at [icon.png](icon.png) in the repository root. Copy mcp-directory/manifest.json to the bundle root after pnpm build so the generated archive contains root-level manifest.json, icon.png, build/, package.json, and production node_modules/.

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

pnpm prepare:mcpb

The staged package is written to dist/mcpb/ with production dependencies installed using npm's flat layout.

CLI Usage

harness-mcp-v2 [stdio|http] [--port ]

Options:
  --port   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:

| Endpoint | Method | Description | | --------- | --------- | ---------------------------------------------------------------- | | /mcp | POST | MCP JSON-RPC endpoint (initialize + session requests) | | /mcp | GET | SSE stream for server-initiated messages (progress, elicitation) | | /mcp | DELETE | Terminate an active MCP session | | /mcp | OPTIONS | CORS preflight | | /health | GET | Health check — returns { "status": "ok", "sessions": } |

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 any shared or remotely reachable deployment. When set, every POST, GET, and DELETE request to /mcp must include Authorization: Bearer .
• Non-loopback 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 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.

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: " \
  -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: "

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: > > ``json > { > "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 p

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: harness
• Source: harness/mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.