# 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 http) | stdio |
| `--port` | The port to listen on (for http) | 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 Agents.
To start the server in this mode, use the following configuration:
```json
{
"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.
Server-Sent Events (`sse`)
The legacy `sse` transport, deprecated by the MCP specification, has been removed.
Clients connecting over `sse` must switch to Streamable HTTP.
To use Streamable HTTP (`http`), start the server with:
```shell
export KUBECONFIG=$HOME/.kube/config
flux-operator-mcp serve --transport http --port 8080
```
To connect to the server over http, use the following configuration:
```json
{
"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:
```json
{
"flux-operator-mcp":{
"command":"flux-operator-mcp",
"args":[
"serve",
"--read-only"
],
"env":{
"KUBECONFIG":"/path/to/.kube/config"
}
}
}
```
Warning
In read-only mode, the MCP [tools](/docs/mcp/tools/) that modify the cluster state
(reconcile, suspend, resume, apply, delete) are disabled.
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:
```json
{
"flux-operator-mcp":{
"command":"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:
```json
{
"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](/docs/resourcesets/app-definition/) with the following configuration:
```yaml
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](/docs/charts/flux-operator-mcp/).
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:
```shell
kubectl port-forward -n flux-system svc/flux-operator-mcp 9090:9090
```
Then, in your `.mcp.json`, add:
```json
{
"mcpServers": {
"flux-operator-mcp": {
"type": "http",
"url": "http://localhost:8080/mcp"
}
}
}
```
Warning
Note that when running in-cluster, the kubeconfig context switching tools are disabled,
the only context available is for the cluster where the MCP server is deployed. To
compare deployments across multiple clusters, you will need to deploy the MCP server
in each cluster and configure each one in your AI assistant.