> 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/use-harness-ai/connect-with-ai/index/environment-variables.md).
# Environment variables reference
Full configuration reference for the Harness MCP Server, including identity, reliability, access control, logging, semantic search, and toolset filtering.
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-ai/use-harness-ai/connect-with-ai/index/resource-types.md): Review what each toolset exposes and which operations it supports.
* [Approvals and safety](/harness-ai/use-harness-ai/connect-with-ai/index/approvals-and-safety.md): Combine toolset filtering with auto-approve thresholds.
* [Configure your AI client](/harness-ai/use-harness-ai/connect-with-ai/index/configure-ai-clients.md): Set variables in a client configuration file.