Flux MCP Server Configuration

This document covers the configuration options for the Flux Model Context Protocol (MCP) Server, including transport modes, security settings, and how to restrict access to your clusters.

Configuration Options

The flux-operator-mcp serve command accepts the following flags:

Transport Modes

Standard Input/Output (stdio)

The MCP Server uses standard input/output (stdio) by default, which is compatible with most AI Agents.

To start the server in this mode, use the following configuration:

{
  "mcpServers": {
    "flux-operator-mcp": {
      "command": "flux-operator-mcp",
      "args": ["serve"],
      "env": {
        "KUBECONFIG": "/path/to/.kube/config"
      }
    }
  }
}

Replace /path/to/.kube/config with the absolute path to your kubeconfig file.

Streamable HTTP (http)

Web-based transport that allows the server to push updates to the client. The diff_kubernetes_manifest tool’s yaml_path input is advertised only when the server runs locally over the stdio transport. It is not included in the tool schema for the http transport or in-cluster deployments; use yaml_content instead. The server implements the MCP specification 2026-07-28 and runs in stateless mode: no session state is kept between requests, so the server can be scaled horizontally behind a load balancer without sticky sessions. Clients using older versions of the MCP specification are supported through protocol version negotiation.

To use Streamable HTTP (http), start the server with:

export KUBECONFIG=$HOME/.kube/config
flux-operator-mcp serve --transport http --port 8080

To connect to the server over http, use the following configuration:

{
  "mcpServers": {
    "flux-operator-mcp": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Security Options

Read-only Mode

In production environments, you can run the server in read-only mode to prevent any modifications to your clusters:

{
  "flux-operator-mcp":{
    "command":"flux-operator-mcp",
    "args":[
      "serve",
      "--read-only"
    ],
    "env":{
      "KUBECONFIG":"/path/to/.kube/config"
    }
  }
}

The diff_kubernetes_manifest tool is available in read-only mode because it never mutates the cluster. Kubernetes authorizes server-side dry-run like a real apply, so the MCP identity needs get and patch on the manifest kinds, plus get on owner kinds and on ConfigMaps and Secrets used by substituteFrom or copyFrom. A view-only identity receives per-object forbidden errors.

Secret Masking

By default, the server masks sensitive values in Kubernetes Secrets. You can disable this if needed:

{
  "flux-operator-mcp":{
    "command":"flux-operator-mcp",
    "args":[
      "serve",
      "--mask-secrets=false"
    ],
    "env":{
      "KUBECONFIG":"/path/to/.kube/config"
    }
  }
}

Service Account Impersonation

For tighter security control, you can configure the server to impersonate a specific service account:

{
  "flux-operator-mcp":{
    "command":"flux-operator-mcp",
    "args":[
      "serve",
      "--kube-as=system:serviceaccount:my-namespace:my-service-account"
    ],
    "env":{
      "KUBECONFIG":"/path/to/.kube/config"
    }
  }
}

This limits the server’s permissions to those granted to the specified service account. Note that your user set in the kubeconfig must have permission to impersonate service accounts.

Deploy on Kubernetes

To deploy the Flux MCP Server in a Kubernetes cluster, you can create a ResourceSet with the following configuration:

apiVersion: fluxcd.controlplane.io/v1
kind: ResourceSet
metadata:
  name: flux-operator-mcp
  namespace: flux-system
spec:
  inputs:
    - readonly: false
      accessFrom: flux-system
  resources:
    - apiVersion: source.toolkit.fluxcd.io/v1
      kind: OCIRepository
      metadata:
        name: << inputs.provider.name >>
        namespace: << inputs.provider.namespace >>
      spec:
        interval: 60m
        url: oci://ghcr.io/controlplaneio-fluxcd/charts/flux-operator-mcp
        layerSelector:
          mediaType: "application/vnd.cncf.helm.chart.content.v1.tar+gzip"
          operation: copy
        ref:
          semver: "*"
    - apiVersion: helm.toolkit.fluxcd.io/v2
      kind: HelmRelease
      metadata:
        name: << inputs.provider.name >>
        namespace: << inputs.provider.namespace >>
      spec:
        serviceAccountName: flux-operator
        chartRef:
          kind: OCIRepository
          name: << inputs.provider.name >>
        interval: 30m
        values:
          transport: http
          readonly: << inputs.readonly >>
          networkPolicy:
            ingress:
              namespaces: [<< inputs.accessFrom >>]

See the full docs and values API for the Helm chart.

This ResourceSet will create a Kubernetes Deployment for the Flux MCP Server with cluster-admin permissions. It is recommended to set the readonly input to true in production environments to prevent modifications to the cluster state.

The server is exposed via a Kubernetes Service named flux-operator-mcp in the flux-system namespace, listening on port 9090. If the MCP client is running in-cluster, the accessFrom input should be set to the name of the namespace where the MCP client is deployed.

To connect to the server, start port forwarding with:

kubectl port-forward -n flux-system svc/flux-operator-mcp 9090:9090

Then, in your .mcp.json, add:

{
  "mcpServers": {
    "flux-operator-mcp": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}