> 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/environment-variables.md).
# Environment variables reference
Every server setting is supplied through an environment variable. Variables are grouped below by purpose. Only `HARNESS_API_KEY` is required, and only in `single-user` mode.
***
### Deployment and identity
| Variable | Required | Default | Description |
| ----------------------------------------- | ------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HARNESS_MCP_MODE` | No | `single-user` | Deployment mode: `single-user` (API key set once in server config, used for all sessions) or `multi-user` (HTTP transport only, per-session credentials supplied via the `x-harness-api-key` header and optional `x-harness-account-id` header) |
| `HARNESS_API_KEY` | Yes in `single-user` mode | -- | Harness personal access token or service account token. Required in `single-user` mode. Must not be set in `multi-user` mode, because the server holds no Harness credentials of its own |
| `HARNESS_ACCOUNT_ID` | No | *(from PAT/SAT)* | Harness account identifier. Auto-extracted from PAT or SAT tokens in `single-user` mode. In `multi-user` mode, sessions can supply their own account ID via the `x-harness-account-id` header when the API key does not embed one |
| `HARNESS_BASE_URL` | No | `https://app.harness.io` | Harness API and UI base URL for local stdio or self-hosted HTTP deployments. Set this to your own instance (for example, `https://harness0.harness.io`) when self-hosting. It has no effect on the managed `https://mcp.harness.io/mcp` hosted endpoint |
| `HARNESS_ORG` | No | -- | Organization ID used when `org_id` is not specified per tool call. If omitted, pass `org_id` explicitly, or let agents discover orgs dynamically via `harness_list(resource_type="organization")` |
| `HARNESS_PROJECT` | No | -- | Project ID used when `project_id` is not specified per tool call. If omitted, pass `project_id` explicitly, or let agents discover projects dynamically via `harness_list(resource_type="project")` |
| `HARNESS_DEFAULT_ORG_ID` (Deprecated) | No | -- | Deprecated alias for `HARNESS_ORG` |
| `HARNESS_DEFAULT_PROJECT_ID` (Deprecated) | No | -- | Deprecated alias for `HARNESS_PROJECT` |
***
### Feature Management & Experimentation
| Variable | Required | Default | Description |
| ---------------------- | -------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HARNESS_FME_API_KEY` | No | -- | Optional Split or FME Admin API credential used for `fme_` resources in self-hosted deployments. Accepts a legacy Split admin key or an FME-entitled Harness PAT or SAT. FME calls go directly to `api.split.io`, so hosted OAuth or service-routing credentials for Harness platform APIs do not authenticate these requests. Must not be set in `multi-user` mode; FME uses each session's `x-harness-api-key` credential instead. If unset, FME falls back to a non-placeholder `HARNESS_API_KEY` for self-hosted sessions |
| `HARNESS_FME_BASE_URL` | No | `https://api.split.io` | Split or FME Admin API base URL used by `fme_` resources. HTTP URLs require `HARNESS_ALLOW_HTTP=true` for local development |
***
### Requests and reliability
| Variable | Required | Default | Description |
| -------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HARNESS_API_TIMEOUT_MS` | No | `30000` | HTTP request timeout in milliseconds |
| `HARNESS_MAX_RETRIES` | No | `3` | Retry count for transient failures (429, 5xx) |
| `HARNESS_MAX_BODY_SIZE_MB` | No | `10` | Max HTTP request body size in MB for `http` transport |
| `HARNESS_RATE_LIMIT_RPS` | No | `10` | Client-side request throttle (requests per second) to Harness APIs |
| `HARNESS_ALLOW_HTTP` | No | `false` | Allow non-HTTPS URLs for `HARNESS_BASE_URL`, `HARNESS_FME_BASE_URL`, and `HARNESS_AUDIT_WEBHOOK_URL`. The server enforces HTTPS by default; set to `true` only for local development against non-TLS endpoints |
***
### Tool and access control
| Variable | Required | Default | Description |
| --------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `HARNESS_TOOLSETS` | No | *(defaults)* | Comma-separated toolset list. Empty loads the default toolsets. Supports `+name` to include an opt-in toolset and `-name` to remove a default toolset. Go to [Toolset filtering](#toolset-filtering) to review the toolset catalog |
| `HARNESS_READ_ONLY` | No | `false` | Block all mutating operations (create, update, delete, execute). Only list and get operations are allowed. Useful for shared or demo environments |
| `HARNESS_AUTO_APPROVE_RISK` | No | `none` | Risk-based auto-approve threshold for autonomous workflows. Operations at or below this risk level proceed without user confirmation. Values: `none`, `low_write`, `medium_write`, `high_write`, `all` |
| `HARNESS_SKIP_ELICITATION` (Deprecated) | No | `false` | Superseded by `HARNESS_AUTO_APPROVE_RISK`. Setting `true` is equivalent to `HARNESS_AUTO_APPROVE_RISK=all` and logs a deprecation warning to stderr. If both are set, `HARNESS_AUTO_APPROVE_RISK` takes precedence |
| `HARNESS_PIPELINE_VERSION` | No | `0` | **(Alpha)** Pipeline YAML version. `0` loads the `pipeline` resource type and excludes `pipeline_v1`; `1` loads `pipeline_v1` and excludes `pipeline`. HTTP sessions can override this at initialize time with the `x-harness-pipeline-version` header set to `0` or `1` |
***
### HTTP transport and multi-user access
| Variable | Required | Default | Description |
| ---------------------------------------- | ------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HARNESS_MCP_ALLOWED_HOSTS` | No | -- | Comma-separated hostnames allowed by HTTP transport Host-header validation. `mcp.harness.io` is allowed by default for localhost binds; add proxy or custom domains here |
| `HARNESS_MCP_AUTH_TOKEN` | Yes for non-loopback HTTP binds | -- | Bearer token required on `/mcp` HTTP routes when set. Required by default when HTTP transport binds to a non-loopback host, unless `HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP=true` |
| `HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP` | No | `false` | Explicitly allow unauthenticated HTTP transport on non-loopback binds. Use only behind another authenticated control |
***
### Logging and audit
| Variable | Required | Default | Description |
| ---------------------------------- | -------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `LOG_LEVEL` | No | `info` | Log verbosity: `debug`, `info`, `warn`, `error` |
| `HARNESS_MCP_LOG_FILE` | No | `~/.claude/harness-mcp.log` | File used for stdio disconnect and crash diagnostics when stderr is no longer available |
| `HARNESS_AUDIT_FILE` | No | -- | Append audit events to a newline-delimited JSON file for durable local collection |
| `HARNESS_AUDIT_WEBHOOK_URL` | No | -- | HTTPS endpoint that receives batched audit events. HTTP URLs require `HARNESS_ALLOW_HTTP=true` for local development |
| `HARNESS_AUDIT_WEBHOOK_TOKEN` | No | -- | Optional bearer token sent to the audit webhook |
| `HARNESS_AUDIT_WEBHOOK_BATCH_SIZE` | No | `10` | Number of audit events to batch before webhook flush |
| `HARNESS_AUDIT_WEBHOOK_FLUSH_MS` | No | `5000` | Max time to hold audit events before webhook flush |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | No | -- | Enables OpenTelemetry audit spans when the optional OpenTelemetry packages are installed |
***
### Semantic search
| Variable | Required | Default | Description |
| -------------------------------- | ----------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `HARNESS_SEARCH_PROVIDER` | No | `local` | Semantic search backend for `harness_search`: `local` (in-process ONNX embeddings), `remote` (external search service over HTTP, required for `multi-user` mode), or `none` (disable semantic search and fall back to keyword scatter-gather only). Use `none` in air-gapped environments or when startup model loading is undesirable |
| `HARNESS_SEARCH_SERVICE_URL` | Yes when `HARNESS_SEARCH_PROVIDER=remote` | -- | Base URL of the remote search service when `HARNESS_SEARCH_PROVIDER=remote` (for example, `http://search-svc:8080`) |
| `HARNESS_SEARCH_SERVICE_HEADERS` | No | -- | JSON object of headers sent with every request to the remote search service. Supports any auth scheme, for example `{"Authorization":"Bearer tok"}` or `{"x-api-key":"key"}` |
| `HARNESS_HF_CACHE_DIR` | No | `/tmp/hf-cache` | Directory for the `@huggingface/transformers` model cache used by the `local` search provider. The Docker image pre-bakes the model into `/app/.cache/hf` to avoid runtime downloads. Set to a persistent volume path in production deployments |
***
### Toolset filtering
By default, all 30 toolsets (and their 139 resource types) are enabled. Use `HARNESS_TOOLSETS` to expose only the toolsets you need, which reduces the resource types the LLM sees and improves tool-selection accuracy.
```bash
# Only expose pipelines, services, and connectors
HARNESS_TOOLSETS=pipelines,services,connectors
```
| Toolset | Resource Types |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent-pipelines` | agent, agent\_run |
| `platform` | organization, project |
| `pipelines` | pipeline, execution, trigger, pipeline\_summary, input\_set, runtime\_input\_template, approval\_instance |
| `services` | service |
| `environments` | environment |
| `connectors` | connector, connector\_catalogue |
| `infrastructure` | infrastructure |
| `secrets` | secret |
| `logs` | execution\_log |
| `audit` | audit\_event |
| `delegates` | delegate, delegate\_token |
| `repositories` | repository, branch, commit, file\_content, tag, repo\_rule, space\_rule |
| `registries` | registry, artifact, artifact\_version, artifact\_file |
| `templates` | template |
| `dashboards` | dashboard, dashboard\_data |
| `idp` | idp\_entity, scorecard, scorecard\_check, scorecard\_stats, scorecard\_check\_stats, idp\_score, idp\_workflow, idp\_tech\_doc |
| `pull-requests` | pull\_request, pr\_reviewer, pr\_comment, pr\_check, pr\_activity |
| `feature-flags` | fme\_workspace, fme\_environment, fme\_feature\_flag, fme\_feature\_flag\_definition, fme\_rollout\_status, fme\_rule\_based\_segment, fme\_rule\_based\_segment\_definition, feature\_flag |
| `gitops` | gitops\_agent, gitops\_application, gitops\_cluster, gitops\_repository, gitops\_applicationset, gitops\_repo\_credential, gitops\_app\_event, gitops\_pod\_log, gitops\_managed\_resource, gitops\_resource\_action, gitops\_dashboard, gitops\_app\_resource\_tree |
| `chaos` | chaos\_experiment, chaos\_probe, chaos\_experiment\_template, chaos\_infrastructure, chaos\_experiment\_variable, chaos\_experiment\_run, chaos\_loadtest, chaos\_k8s\_infrastructure, chaos\_hub, chaos\_fault, chaos\_network\_map, chaos\_guard\_condition, chaos\_guard\_rule, chaos\_recommendation, chaos\_risk |
| `ccm` | cost\_perspective, cost\_breakdown, cost\_timeseries, cost\_summary, cost\_recommendation, cost\_anomaly, cost\_anomaly\_summary, cost\_category, cost\_account\_overview, cost\_filter\_value, cost\_recommendation\_stats, cost\_recommendation\_detail, cost\_commitment |
| `sei` | sei\_metric, sei\_productivity\_metric, sei\_dora\_metric, sei\_team, sei\_team\_detail, sei\_org\_tree, sei\_org\_tree\_detail, sei\_business\_alignment, sei\_ai\_usage, sei\_ai\_adoption, sei\_ai\_impact, sei\_ai\_raw\_metric |
| `scs` | scs\_artifact\_source, artifact\_security, scs\_artifact\_component, scs\_artifact\_remediation, scs\_chain\_of\_custody, scs\_compliance\_result, code\_repo\_security, scs\_sbom |
| `sto` | security\_issue, security\_issue\_filter, security\_exemption |
| `access_control` | user, user\_group, service\_account, role, role\_assignment, resource\_group, permission |
| `governance` | policy, policy\_set, policy\_evaluation |
| `freeze` | freeze\_window, global\_freeze |
| `overrides` | service\_override |
| `settings` | setting |
| `visualizations` | visual\_timeline, visual\_stage\_flow, visual\_health\_dashboard, visual\_pie\_chart, visual\_bar\_chart, visual\_timeseries, visual\_architecture |
***
### Next steps
* [Resource types](/harness-platform/use-harness-ai/harness-ai/connect-with-ai/harness-mcp-server/resource-types.md): Review what each toolset exposes and which operations it supports.
* [Approvals and safety](/harness-platform/use-harness-ai/harness-ai/connect-with-ai/harness-mcp-server/approvals-and-safety.md): Combine toolset filtering with auto-approve thresholds.
* [Configure your AI client](/harness-platform/use-harness-ai/harness-ai/connect-with-ai/harness-mcp-server/configure-ai-clients.md): Set variables in a client configuration file.