Configuration Options - cturner8/kube-mcp GitHub Wiki

MCP Server Configuration

The MCP server can be customised via CLI flags, environment variables, or Helm chart values.

Important: All environment variables are prefixed with KUBE_MCP_. When using Helm chart deployment, configuration values are nested within the mcp block in values.yaml.

Configuration Precedence

Configuration is evaluated in the following order (highest to lowest priority):

CLI Flags - Command-line arguments passed when starting the server
Environment Variables - Environment variables set in the container/shell
Helm Chart Values - Values provided in the Helm chart's values.yaml. These populate the relevant environment variables in the container deployment.

Core Configuration

Required values are marked in bold.

Important: All environment variables are prefixed with KUBE_MCP_. When using Helm chart deployment, configuration values are nested within the mcp block in values.yaml.

Option	Description	Default	Environment Variable	CLI Flag	Chart Key
Hostname	Hostname for the HTTP API to listen on.	-	`HOST`	`host`	`mcp.host`
Port	Port for the HTTP API to listen on.	`9000`	`PORT`	`port`	`service.port`
Base URL	URL where the MCP server is externally accessible.	-	`BASE_URL`	`base-url`	`mcp.baseUrl`
OIDC Issuer URL	URL of the OIDC Issuer to use for authentication.	-	`OIDC_ISSUER_URL`	`oidc-issuer-url`	`mcp.oidc.issuerUrl`
OIDC Client ID	ID of the OIDC Client to use for authentication.	-	`OIDC_CLIENT_ID`	`oidc-client-id`	`mcp.oidc.clientId`
OIDC Signing Method	Signing method used by the OIDC Issuer to sign tokens.	`RS256`	`OIDC_SIGNING_METHOD`	`oidc-signing-method`	`mcp.oidc.signingMethod`
OIDC Scopes	Scopes required for authentication.	`openid`	`OIDC_SCOPES`	`oidc-scopes`	`mcp.oidc.scopes`
Allowed Origins	Comma separated list of origins to grant CORS access to. Useful if the MCP server will be accessed from the browser.	-	`ALLOWED_ORIGINS`	`allowed-origins`	`mcp.allowedOrigins`
Log Level	Controls the default level of logging the application will emit. Valid values: `debug`, `info`, `warn`, `error`.	`error`	`LOG_LEVEL`	`log-level`	`mcp.logging.level`
Allowed Tools	Comma separated list of tools to allow. If empty, all tools are allowed. Cannot be used in combination with "Disallowed Tools".	-	`ALLOWED_TOOLS`	`allowed-tools`	`mcp.tools.allowed`
Disallowed Tools	Comma separated list of tools to disallow. If empty, no tools are disallowed. Cannot be used in combination with "Allowed Tools".	`list_secrets,list_config_maps,get_secret,get_config_map`	`DISALLOWED_TOOLS`	`disallowed-tools`	`mcp.tools.disallowed`

See Also:

Authentication and Authorisation - Detailed authentication setup and OAuth2 configuration

MCP Tools - Complete list of available tools for filtering

Debugging - Using log levels for troubleshooting

Configuration Examples

Minimal Production Configuration (Environment Variables)

export KUBE_MCP_BASE_URL="https://mcp.example.com"
export KUBE_MCP_OIDC_ISSUER_URL="https://auth.example.com"
export KUBE_MCP_OIDC_CLIENT_ID="your-client-id"

Development Configuration with CLI Flags

go run . \
  --base-url "http://localhost:9000" \
  --oidc-issuer-url "https://auth.localhost:8443" \
  --oidc-client-id "dev-client-id" \
  --out-of-cluster \
  --log-level debug \
  --allowed-origins "http://localhost:3000,http://localhost:5173"

Helm Chart Configuration

mcp:
  host: "0.0.0.0"
  baseUrl: "https://mcp.example.com"
  oidc:
    issuerUrl: "https://auth.example.com"
    clientId: "your-client-id"
    signingMethod: "RS256"
    scopes: "openid,profile,email"
  allowedOrigins: "https://app.example.com"
  logging:
    level: "info"
  tools:
    # Only allow read operations, exclude secrets
    disallowed: "list_secrets,list_config_maps,get_secret,get_config_map"

Configuration Validation

Important: The server will fail to start if:

Required fields (Base URL, OIDC Issuer URL, OIDC Client ID) are not provided

Both allowed-tools and disallowed-tools are specified simultaneously

Invalid log level is provided (must be debug, info, warn, or error)

Invalid OIDC signing method is specified

For tool filtering conflicts, the server will exit with an error message. Choose either an allowlist approach (specify tools to enable) or a blocklist approach (specify tools to disable), but not both.

Development & Testing Flags

The following configuration options are available through CLI flag only and are intended for development and testing environments:

Flag	Description	Default
`out-of-cluster`	Run outside a Kubernetes cluster using kubeconfig. Required for local development.	`false` (in-cluster)
`kubeconfig`	Path to kubeconfig file when running with `--out-of-cluster`. Only used in out-of-cluster mode.	`~/.kube/config`

Warning: These flags should not be used in production Kubernetes deployments. The server automatically detects in-cluster configuration when running as a pod. See Development Environment for local setup instructions.

Chart Deployment Configuration

The following options control the Kubernetes deployment, service, and pod configuration when deploying via Helm chart.

Application Configuration

Option	Description	Default	Chart Key
Replica Count	Number of pod replicas to run.	`1`	`replicaCount`
Name Override	Override the chart name used in resource names.	-	`nameOverride`
Full Name Override	Override the full resource name (chart name + release name).	-	`fullnameOverride`

Image Configuration

Option	Description	Default	Chart Key
Repository	Container image repository.	`ghcr.io/cturner8/kube-mcp`	`image.repository`
Pull Policy	Image pull policy (`Always`, `IfNotPresent`, `Never`).	`IfNotPresent`	`image.pullPolicy`
Tag	Image tag to use. Defaults to chart appVersion if not specified.	Chart `appVersion`	`image.tag`
Pull Secrets	Secrets for pulling from private registries.	`[]`	`imagePullSecrets`

Service Account & RBAC

Option	Description	Default	Chart Key
Create Service Account	Whether to create a service account.	`true`	`serviceAccount.create`
Automount Credentials	Automatically mount ServiceAccount API credentials.	`true`	`serviceAccount.automount`
Service Account Annotations	Annotations to add to the service account.	`{}`	`serviceAccount.annotations`
Service Account Name	Name of service account. Generated from chart name if not specified.	-	`serviceAccount.name`
Create RBAC Resources	Whether to create Role and RoleBinding resources.	`true`	`rbac.create`
RBAC Annotations	Annotations to add to RBAC resources.	`{}`	`rbac.annotations`
RBAC Name	Name of RBAC resources. Generated from chart name if not specified.	-	`rbac.name`
RBAC Rules	Array of RBAC rules defining API access permissions. See values.yaml for defaults.	See RBAC	`rbac.rules`

Note: RBAC rules should align with the MCP tools you enable. The default rules grant read-only access to core Kubernetes resources. See RBAC for more details.

If the generated service account and RBAC resources need more customisation than the chart provides, you can disable these from being automatically created using serviceAccount.create and rbac.create then provide your own.

Pod Configuration

Option	Description	Default	Chart Key
Pod Annotations	Kubernetes annotations to add to pods.	`{}`	`podAnnotations`
Pod Labels	Kubernetes labels to add to pods.	`{}`	`podLabels`
Pod Security Context	Security context for the pod.	`{}`	`podSecurityContext`
Security Context	Security context for the container.	See below	`securityContext`
Node Selector	Node labels for pod assignment.	`{}`	`nodeSelector`
Tolerations	Tolerations for pod assignment.	`[]`	`tolerations`
Affinity	Affinity rules for pod assignment.	`{}`	`affinity`

Default Security Context:

securityContext:
  capabilities:
    drop: [ALL]
  readOnlyRootFilesystem: true
  runAsUser: 10001
  runAsNonRoot: true
  allowPrivilegeEscalation: false
  privileged: false

Service Configuration

Option	Description	Default	Chart Key
Service Type	Kubernetes service type (`ClusterIP`, `NodePort`, `LoadBalancer`).	`ClusterIP`	`service.type`
Service Port	Port the service listens on.	`9000`	`service.port`

Ingress Configuration

Option	Description	Default	Chart Key
Enabled	Whether to create an Ingress resource.	`false`	`ingress.enabled`
Class Name	Ingress class name (e.g., `nginx`, `traefik`).	-	`ingress.className`
Annotations	Annotations for the Ingress resource.	`{}`	`ingress.annotations`
Hosts	Array of host configurations with paths.	See below	`ingress.hosts`
TLS	TLS configuration for hosts.	`[]`	`ingress.tls`

Default Host Configuration:

hosts:
  - host: localhost
    paths:
      - path: /
        pathType: Prefix

Resource Management

Option	Description	Default	Chart Key
Resources	CPU and memory resource requests and limits.	`{}`	`resources`
Liveness Probe	Liveness probe configuration. Defaults to HTTP GET on `/health`.	See below	`livenessProbe`
Readiness Probe	Readiness probe configuration. Defaults to HTTP GET on `/health`.	See below	`readinessProbe`

Default Probe Configuration:

livenessProbe:
  httpGet:
    path: /health
    port: http
readinessProbe:
  httpGet:
    path: /health
    port: http

Volume Configuration

Option	Description	Default	Chart Key
Volumes	Additional volumes to add to the pod. Useful for mounting configs/secrets.	`[]`	`volumes`
Volume Mounts	Additional volume mounts for the container.	`[]`	`volumeMounts`

Example Volume Configuration:

volumes:
  - name: custom-config
    configMap:
      name: my-config
volumeMounts:
  - name: custom-config
    mountPath: /etc/config
    readOnly: true

Default Chart Configuration

See charts/kube-mcp/values.yaml for the default values.yaml configuration.