> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-ai/untitled-1/use-harness-ai/ide-and-integrations/mcp-server/configure-ai-clients.md).

# Configure your AI client

Add the Harness MCP Server to your editor or terminal so your AI assistant can call Harness tools. Each client below uses the same `npx harness-mcp-v2` command with a Harness API key supplied through the `env` block.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

Before you configure AI client, ensure you have the following:

* **Harness API key**: A PAT in the format `pat.<accountId>.<tokenId>.<secret>`. Go to [Harness MCP Server](/harness-ai/use-harness-ai/harness-ai/connect-with-ai/harness-mcp-server/index.md) to review prerequisites.
* **Node.js**: Required for `npx`. Go to [Install with an alternative method](/harness-ai/use-harness-ai/harness-ai/connect-with-ai/harness-mcp-server/index.md#install-with-an-alternative-method) to review other options.

{% hint style="info" %}
`HARNESS_ORG` and `HARNESS_PROJECT` are optional. Agents can discover orgs and projects dynamically using `harness_list(resource_type="organization")` and `harness_list(resource_type="project")`. Set them only when you want to pin a default scope. The deprecated names `HARNESS_DEFAULT_ORG_ID` and `HARNESS_DEFAULT_PROJECT_ID` are still accepted for backward compatibility.
{% endhint %}

{% hint style="info" %}
**TROUBLESHOOT `NPX ENOENT` OR `NODE: NO SUCH FILE OR DIRECTORY`**

GUI apps (Cursor, Claude Desktop, Windsurf, VS Code) do not inherit your shell's `PATH`, so they often cannot find `npx` or `node`. 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. Common locations:

* **Homebrew (macOS)**: `/opt/homebrew/bin/npx`
* **nvm**: `~/.nvm/versions/node/v20.x.x/bin/npx` (run `nvm which current` for the exact path)
* **System Node**: `/usr/local/bin/npx`
  {% endhint %}

***

### Claude Desktop <a href="#claude-desktop" id="claude-desktop"></a>

To set up AI client on Claude Desktop, navigate to the file location specified below:

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

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

***

### Claude Code <a href="#claude-code" id="claude-code"></a>

To set up AI client on Claude code, run the following commands on the terminal:

```bash
claude mcp add harness -- npx harness-mcp-v2
```

Then set `HARNESS_API_KEY` in your environment or `.env` file.

***

### Cursor <a href="#cursor" id="cursor"></a>

To set up AI client on Cursor, add the following JSON file to `.cursor/mcp.json`, and replace the Harness API key appropriately:

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

***

### VS Code <a href="#vs-code" id="vs-code"></a>

To set up AI client on VS Code, add the following JSON file to `.vscode/mcp.json` or to your VS Code settings, and replace the Harness API key appropriately:

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

***

### Windsurf <a href="#windsurf" id="windsurf"></a>

To set up AI client on Windsurf, add the following JSON file to `~/.windsurf/mcp.json`, and replace the Harness API key appropriately:

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

***

### Gemini CLI <a href="#gemini-cli" id="gemini-cli"></a>

To set up AI client on Gemini CLI, add the following JSON file to `~/.gemini/settings.json`, and replace the Harness API key appropriately:

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

#### Gemini CLI Extensions <a href="#gemini-cli-extensions" id="gemini-cli-extensions"></a>

You can install AI client using Gemini CLI Extensions. You can run the following command in your terminal:

```bash
gemini extensions install https://github.com/harness/mcp-server
export HARNESS_API_KEY="pat.xxx.xxx.xxx"
gemini
```

***

### Amazon Q Developer CLI <a href="#amazon-q-developer-cli" id="amazon-q-developer-cli"></a>

To set up AI client on Amazon Q Developer CLI, add the following JSON file to `~/.aws/amazonq/mcp.json`, and replace the Harness API key appropriately:

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

***

### Next steps <a href="#next-steps" id="next-steps"></a>

* [Tools reference](/harness-ai/use-harness-ai/harness-ai/connect-with-ai/harness-mcp-server/tools-reference.md): Review the tools your agent can now call.
* [Environment variables](/harness-ai/use-harness-ai/harness-ai/connect-with-ai/harness-mcp-server/environment-variables.md): Restrict scope, enable read-only mode, or filter toolsets.
* [Troubleshooting](/harness-ai/use-harness-ai/harness-ai/connect-with-ai/harness-mcp-server/troubleshooting.md): Resolve connection and configuration errors.