ovn-kubernetes-mcp

Repo hosting the Model Context Protocol Server for troubleshooting OVN-Kubernetes.

Table of Contents

• Operating Modes
• How to connect to the MCP Server
  • Command-line options
  • Live Cluster Mode
  • Offline Mode
  • Dual Mode
  • Local development
  • Kubernetes deployment
• Selectively exposing tools
• Tools available in MCP Server
  • Live Cluster Mode
  • Offline Mode

Operating Modes

How to connect to the MCP Server

To use the MCP server, ensure you have Go installed with a version greater than or equal to the version specified in the go.mod file.

The server currently supports 2 transport modes: stdio and http.

Command-line options

Live Cluster Mode

For stdio mode, the server can be run and connected to by using the following configuration in an MCP host (Cursor, Claude, etc.):

{
  "mcpServers": {
    "ovn-kubernetes": {
      "command": "go",
      "args": [
        "run",
        "github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest",
        "--kubeconfig",
        "/PATH-TO-THE-KUBECONFIG-FILE"
      ]
    }
  }
}

For http mode, the server should be started separately:

go run github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest --transport http --kubeconfig /PATH-TO-THE-KUBECONFIG-FILE

The following configuration should be used in an MCP host (Cursor, Claude, etc.) to connect to the server:

{
  "mcpServers": {
    "ovn-kubernetes": {
      "url": "http://localhost:8080"
    }
  }
}

Offline Mode

For offline troubleshooting (e.g., analyzing sosreports, must-gathers), use --mode offline:

For stdio mode:

{
  "mcpServers": {
    "ovn-kubernetes": {
      "command": "go",
      "args": [
        "run",
        "github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest",
        "--mode",
        "offline"
      ]
    }
  }
}

For http mode:

go run github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest --transport http --mode offline

Note: Must-gather tools require the omc binary. Some must-gather tools also require the ovsdb-tool binary; if it is not available, those tools are not registered.

Dual Mode

For using dual live-cluster (needs kubeconfig) and offline tools, use --mode dual:

For stdio mode:

{
  "mcpServers": {
    "ovn-kubernetes": {
      "command": "go",
      "args": [
        "run",
        "github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest",
        "--mode",
        "dual",
        "--kubeconfig",
        "/PATH-TO-THE-KUBECONFIG-FILE"
      ]
    }
  }
}

For http mode:

go run github.com/ovn-kubernetes/ovn-kubernetes-mcp/cmd/ovnk-mcp-server@latest --transport http --mode dual --kubeconfig /PATH-TO-THE-KUBECONFIG-FILE

Local development

When developing or building locally, run make build and use the binary path as the command.

• Use --mode <live-cluster|offline|dual> to choose the mode.
• For live-cluster or dual, add --kubeconfig /path/to/kubeconfig.
• For offline, omit --kubeconfig.

stdio:

{
  "mcpServers": {
    "ovn-kubernetes": {
      "command": "/PATH-TO-THE-LOCAL-GIT-REPO/_output/ovnk-mcp-server",
      "args": [
        "--mode",
        "<live-cluster|offline|dual>",
        "--kubeconfig",
        "/PATH-TO-THE-KUBECONFIG-FILE"
      ]
    }
  }
}

http:

/PATH-TO-THE-LOCAL-GIT-REPO/_output/ovnk-mcp-server --transport http --mode <live-cluster|offline|dual> --kubeconfig /PATH-TO-THE-KUBECONFIG-FILE

For offline mode, omit the --kubeconfig argument in dual examples above.

Kubernetes deployment

The manifests under config/ run the server in the cluster as HTTP (config/deployment.yaml): --transport=http, --host=0.0.0.0, --port=8080, and --mode=live-cluster. There is no --kubeconfig argument in that deployment; the pod uses its ServiceAccount credentials to connect to the Kubernetes API server.

Apply the manifests with:

make deploy-ovnk-mcp-k8s IMAGE=<your-registry>/ovnk-mcp-server:<tag>

IMAGE is optional if the image already matches what the manifests expect. Remove the stack with make undeploy-ovnk-mcp-k8s.

Service: a ClusterIP Service ovnk-mcp-server in namespace ovn-kubernetes-mcp exposes port 8080 to the pod (config/service.yaml).

NetworkPolicy: config/networkpolicy.yaml selects the MCP server pod and sets ingress: [], which denies all ingress to that pod from the cluster network. So other workloads cannot reach the MCP HTTP endpoint through the Service, and there is no in-manifest Ingress or LoadBalancer for public access.

Connecting an LLM client (Cursor, Claude, and so on) from your machine: the usual pattern is to use kubectl port-forward from a kube context that can access the cluster. That forwards a local port to the Service without relying on in-cluster ingress to the pod (the forward is set up by the kubelet). In one terminal:

kubectl port-forward -n ovn-kubernetes-mcp svc/ovnk-mcp-server 8080:8080

Then configure the host’s MCP client for streamable HTTP against the forwarded port (same shape as HTTP live-cluster above):

{
  "mcpServers": {
    "ovn-kubernetes": {
      "url": "http://127.0.0.1:8080"
    }
  }
}

Keep the port-forward process running while you use the tools. The server URL is the base of the HTTP transport; clients that implement MCP Streamable HTTP negotiate on top of that.

Security note: the shipped manifests do not add TLS or application-level auth on the MCP HTTP listener. Treat network access as sensitive: use port-forward or private networking, and rely on Kubernetes RBAC (who may port-forward or change NetworkPolicy) to limit who can reach the server.

Allowing only a trusted in-cluster pod: leave config/networkpolicy.yaml in place. For a pod that is allowed to talk to the MCP server (for example a single well-known automation or gateway workload), add a second NetworkPolicy in namespace ovn-kubernetes-mcp. Policies that select the same pod are additive: allowed ingress is the union of every matching policy’s ingress rules, so the deny-all policy keeps every other source blocked while your new policy explicitly permits the trusted peer on port 8080 only.

1. Give the trusted client pod a narrow, unique label (example below uses app.kubernetes.io/name: ovnk-mcp-trusted-client).
2. Apply a policy that uses the same podSelector as the shipped policy (MCP server labels: app.kubernetes.io/name: ovn-kubernetes-mcp and app.kubernetes.io/component: mcp-server) and an ingress rule whose from matches only that client, with ports limited to 8080 / TCP.

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: ovnk-mcp-server-allow-trusted-client
  namespace: ovn-kubernetes-mcp
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: ovn-kubernetes-mcp
      app.kubernetes.io/component: mcp-server
  policyTypes:
    - Ingress
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app.kubernetes.io/name: ovnk-mcp-trusted-client
      ports:
        - port: 8080
          protocol: TCP

From that client pod, call the Service at http://ovnk-mcp-server.ovn-kubernetes-mcp.svc:8080 (or the fully qualified *.svc.cluster.local name). If the client runs in another namespace, use a from entry with both namespaceSelector and podSelector as described under Targeting multiple namespaces by label. Prefer explicit labels over wide selectors, and keep trusting this path only for workloads you control—there is still no MCP-level authentication on the wire.

Selectively exposing tools

By default the server registers every tool listed in Tools available in MCP Server. Two CLI flags let you hide specific categories or individual tools so clients never see them in tools/list and any direct tools/call against them is rejected:

The two flags can be combined; the union of their resolved tool names is hidden. The startup log line Hiding N tool(s) from clients: ... lists the final set so you can verify the configuration.

Filtering happens at the MCP protocol layer (in middleware), so tools are still registered with the server but never advertised to or callable by clients. Backwards compatible: omitting both flags exposes all tools as before.

Examples

Production-leaning: drop packet capture and the wider kernel toolset.

ovnk-mcp-server --disable-tools=tcpdump,pwru --disable-categories=kernel

Restrict to OVN/OVS introspection and basic Kubernetes lookups.

ovnk-mcp-server --disable-categories=kernel,network-tools,must-gather,sosreport

In a Kubernetes manifest the same options go straight into the container args:

args:
  - --transport=http
  - --host=0.0.0.0
  - --port=8080
  - --mode=live-cluster
  - --disable-tools=tcpdump,pwru
  - --disable-categories=kernel

Tools available in MCP Server

Live Cluster Mode

Available when running with --mode live-cluster or --mode dual (and with a valid kubeconfig).

Offline Mode

Available when running with --mode offline or --mode dual. No cluster access required.