Configuration file reference

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

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

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

See Custom store for the CatalogStore contract.