---
url: /kibana-mcp-server/reference/config-file.md
description: Every option of the configuration file, its precedence and its constraints.
---

# Configuration file reference

Load a file explicitly with `serve --config <path>` or `KIBANA_MCP_CONFIG`. It executes as code; working-directory discovery is disabled.

```ts
import { defineKibanaMcpConfig } from "@havesomecode/kibana-mcp-server/config";

export default defineKibanaMcpConfig({
  // …
});
```

Default-export an object or a function (sync or async) returning it. `defineKibanaMcpConfig` provides types only.

## Options

| Option | Type | Overridden by | Description |
| --- | --- | --- | --- |
| `url` | `string` | `KIBANA_BASE_URL` | Kibana base URL |
| `user` | `string` | `KIBANA_USERNAME` | Kibana user |
| `password` | `string` | `KIBANA_PASSWORD` | Kibana password |
| `timeoutMs` | `number` | `KIBANA_TIMEOUT_MS` | Backend deadline in milliseconds |
| `profile` | `string` | `--profile`, `KIBANA_PROFILE` | Profile served when the transport names none |
| `store` | store or factory | | Where source catalogs are kept. Without it, catalogs are files. |
| `storeOptions` | any | | Handed to the `store` factory |
| `http.host` | `string` | `--host`, `KIBANA_HTTP_HOST` | Listen host |
| `http.port` | `number` | `--port`, `KIBANA_HTTP_PORT` | Listen port |
| `http.path` | `string` | `--path`, `KIBANA_HTTP_PATH` | Endpoint path |
| `http.profileHeader` | `string` | `--profile-header`, `KIBANA_HTTP_PROFILE_HEADER` | Header carrying the profile of the caller |
| `http.authToken` | `string` | `KIBANA_HTTP_AUTH_TOKEN` | Shared secret expected as a bearer token |
| `http.oidc.issuer` | `string` | `KIBANA_HTTP_OIDC_ISSUER` | OpenID Connect issuer protecting the endpoint |
| `http.oidc.resource` | `string` | `KIBANA_HTTP_OIDC_RESOURCE` | Public URL of the MCP endpoint, required with `issuer` |
| `http.oidc.audience` | `string` | `KIBANA_HTTP_OIDC_AUDIENCE` | Expected token audience, default `resource` |
| `http.oidc.mode` | `"offline"` | `"introspection"` | `KIBANA_HTTP_OIDC_MODE` | Token verification, default `introspection` with a client id, `offline` otherwise |
| `http.oidc.clientId` | `string` | `KIBANA_HTTP_OIDC_CLIENT_ID` | Client used for introspection |
| `http.oidc.clientSecret` | `string` | `KIBANA_HTTP_OIDC_CLIENT_SECRET` | Secret of that client |
| `http.oidc.requiredScopes` | `string[]` | `KIBANA_HTTP_OIDC_REQUIRED_SCOPES` | Scopes every token must carry |
| `http.oidc.scopesSupported` | `string[]` | `KIBANA_HTTP_OIDC_SCOPES_SUPPORTED` | Scopes advertised to clients |
| `http.oidc.profileClaim` | `string` | `KIBANA_HTTP_OIDC_PROFILE_CLAIM` | Claim naming the caller at the issuer, default `sub`; the profile is `<issuer>#<claim value>` |
| `http.oidc.allowInsecureRequests` | `boolean` | `KIBANA_HTTP_OIDC_ALLOW_INSECURE_REQUESTS` | Allow a non-HTTPS issuer or resource. Development only. |

## Precedence

Command-line flag → environment variable → configuration file → built-in default.

## Constraints

* `store` requires `url`, `user` and `password`, from the file or from the environment.
* `store` cannot be combined with `KIBANA_SOURCE_CATALOG_PATH`.
* Without `store`, direct connections require explicit `KIBANA_SOURCE_CATALOG_PATH`; saved profiles use their saved path. No implicit catalog path.
* `http.oidc` excludes `http.authToken` and `http.profileHeader`, requires named profiles, and its `resource` path must be `http.path`.
* A `.ts` file needs Node.js 22.18 or later. A `.mjs` file works on every supported version.
* The package must resolve from the file's directory for its import to work.

## Types

```ts
import type { CatalogStore } from "@havesomecode/kibana-mcp-server/config";
import { CatalogConflictError } from "@havesomecode/kibana-mcp-server/config";
```

See [Custom store](../deployment/stores/custom) for the `CatalogStore` contract.