> 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-platform/use-harness-ai/harness-ai/connect-with-ai/harness-mcp-server/troubleshooting.md).

# Troubleshooting

Use this page to resolve errors related to startup, authentication, and tool-calls. For more information on Hosted MCP OAuth failures, see [Harness Hosted MCP](/harness-platform/use-harness-ai/harness-ai/connect-with-ai/harness-mcp-server/hosted-mcp.md#troubleshooting). If sign-in fails at your SAML or OIDC Identity Provider, add the MCP-specific ACS URL or redirect URI as described in [Single Sign-On (SSO) for Harness MCP](/harness-platform/use-harness-platform/authentication/single-sign-on-for-harness-mcp.md).

***

### Debug with MCP Inspector <a href="#debug-with-mcp-inspector" id="debug-with-mcp-inspector"></a>

Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to debug the server interactively:

```bash
npx @modelcontextprotocol/inspector npx harness-mcp-v2
```

The Inspector displays a URL you can open in your browser to inspect tool calls and responses.

***

### Common issues <a href="#common-issues" id="common-issues"></a>

<details>

<summary>HARNESS_ACCOUNT_ID is required when the API key is not a PAT</summary>

Your API key is not in PAT format (pat...), so the account ID cannot be auto-extracted. Set the HARNESS\_ACCOUNT\_ID environment variable explicitly.

</details>

<details>

<summary>npx ENOENT or node: No such file or directory when using GUI clients</summary>

GUI apps (Cursor, Claude Desktop, Windsurf, VS Code) do not inherit your shell's PATH. Use absolute paths for the command and explicitly set PATH in the env block of your MCP config. Run 'which npx' and 'which node' in a terminal to find the correct paths.

</details>

<details>

<summary>Unknown resource_type error from tools</summary>

The resource type is misspelled or filtered out via HARNESS\_TOOLSETS. Call harness\_describe (with optional search\_term) to discover valid resource types.

</details>

<details>

<summary>Missing required field for path parameter</summary>

A project or org scoped call is missing identifiers. Set the HARNESS\_ORG and HARNESS\_PROJECT environment variables, or pass org\_id and project\_id per tool call.

</details>

<details>

<summary>Read-only mode is enabled and write operations are not allowed</summary>

HARNESS\_READ\_ONLY=true blocks create, update, delete, and execute operations. Set HARNESS\_READ\_ONLY=false if write operations are intended.

</details>

<details>

<summary>Pipeline run fails with unresolved required inputs</summary>

Your inputs did not cover all required runtime placeholders. Fetch the runtime\_input\_template first, then supply missing keys via inputs or use input\_set\_ids for structural inputs.

</details>

<details>

<summary>HARNESS_BASE_URL must use HTTPS</summary>

The server enforces HTTPS by default. If you need HTTP for local development, set HARNESS\_ALLOW\_HTTP=true.

</details>

<details>

<summary>Operation declined by user</summary>

The user declined the elicitation confirmation dialog. Verify the operation details and retry if intended.

</details>

<details>

<summary>HTTP mcp-session-id header is required or Session not found</summary>

Send an initialize request first to create a session, then include the mcp-session-id header on all subsequent POST, GET, and DELETE requests to /mcp. Sessions expire after 30 minutes of idle time.

</details>

<details>

<summary>VS Code stuck in a session 404 or 401 reconnect loop</summary>

VS Code may repeatedly log a cycle like this in the MCP server output and never recover:

\`\`\`text Connection state: Running Connection state: Error 404 status sending message to <https://mcp.harness.io/mcp>: {"jsonrpc":"2.0","error":{"code":-32000,"message":"Session not found. Send an initialize request to start a new session."},"id":null}; will retry with new session ID \`\`\`

You may also see a 401 response with a \`www-authenticate\` header that never resolves into a completed sign-in prompt.

This is caused by a known VS Code behavior ([microsoft/vscode#253854](https://github.com/microsoft/vscode/issues/253854)): VS Code caches the dynamic authentication provider for an MCP server so it does not re-prompt you on every connection. When that cached authentication or registration goes stale, the server returns a 401 or 404, and VS Code retries with the same stale state instead of starting a fresh OAuth flow.

**Resolution:** Remove the cached dynamic authentication provider, then reconnect.

1. Open the Command Palette and run **MCP: Remove Dynamic Authentication Provider** (or open the Account menu in the lower-left corner and sign out of the Harness dynamic authentication entry).
2. Reload the window or restart the MCP server.
3. Reconnect and complete the OAuth sign-in flow again.

You do not need to reinstall VS Code or clear its full local state to resolve this.

</details>

***

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

* [Environment variables](/harness-platform/use-harness-ai/harness-ai/connect-with-ai/harness-mcp-server/environment-variables.md): Configure logging and audit output.
* [Harness MCP Server source code](https://github.com/harness/mcp-server): Open an issue against the server.
* [Manage API Keys](/harness-platform/use-harness-platform/automation/api/add-and-manage-api-keys.md): Rotate or recreate a token.