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:

Flag	Description	Default
--transport	The transport protocol (stdio or sse)	stdio
--port	The port to listen on (for sse)	8080
--read-only	Run in read-only mode	false
--mask-secrets	Mask secret values	true
--kube-as	Kubernetes account to impersonate	none

Transport Modes

Standard Input/Output (stdio)

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

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

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

Server-Sent Events (SSE)

Web-based transport that allows the server to push updates to the client.

To use Server-Sent Events (SSE), start the server with:

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

To connect to the server from VS Code, use the following configuration:

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

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":"/path/to/flux-operator-mcp",
    "args":[
      "serve",
      "--read-only"
    ],
    "env":{
      "KUBECONFIG":"/path/to/.kube/config"
    }
  }
}

Warning

In read-only mode, the MCP tools that modify the cluster state (reconcile, suspend, resume, apply, delete) are disabled.

Secret Masking

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

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

Warning

Disabling secret masking will expose sensitive information to the AI assistant and potentially to its training data. Only disable this in controlled environments when using self-hosted models.

Service Account Impersonation

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

{
  "flux-operator-mcp":{
    "command":"/path/to/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.

Docker Container

While it is possible to run the Flux MCP Server in a Docker container and mount the kubeconfig file, this could work only when the kubeconfig contains static credentials. If you connect to a managed Kubernetes cluster, the authentication implies shelling out to the cloud provider CLI with access to the other config files.

At the moment, we do not provide a Docker image for the Flux MCP Server, but you can build one using the binaries available on the release page.