Kubeflow MCP Server

Proposal: KEP-936 · ROADMAP · SECURITY · CONTRIBUTING

Overview

The Kubeflow MCP Server exposes Kubeflow Training operations as Model Context Protocol tools, enabling AI agents (Claude, Cursor, Claude Code, or any custom agents etc.) to plan, submit, monitor, and manage training jobs through natural language — without users needing to learn Kubernetes or the Kubeflow SDK directly.

Benefits

Agent-Native: Tools auto-discovered via MCP — no manual API wiring
Guided Workflow: Phase ordering with next-step hints (Plan → Discover → Train → Monitor)
Preview-Before-Submit: Every mutating operation requires explicit confirmation
Security-First: Persona gating, namespace enforcement, input validation, bearer/JWT auth
Multi-Platform: Auto-detects OpenShift, EKS, GKE with platform-specific guidance
Token-Efficient: Progressive/semantic modes compress 23 tools into 2-3 meta-tools
Extensible: Plugin architecture for additional Kubeflow clients (TODO: optimizer, hub)

Demo

Get Started

Install from source

git clone https://github.com/kubeflow/mcp-server.git
cd mcp-server
pip install .

Run the server

kubeflow-mcp serve

Once published to PyPI, install with pip install kubeflow-mcp.

Run with Docker

Pre-built multi-arch images are published to GHCR on every release:

docker run --rm -p 8000:8000 \
  -e KUBEFLOW_MCP_AUTH_TOKEN=my-secret-token \
  ghcr.io/kubeflow/mcp-server:latest

The server listens on http://localhost:8000/mcp.

Container and Kubernetes probes are available without MCP authentication:

GET /health  # liveness: the server process is accepting HTTP requests
GET /ready   # readiness: configured clients imported and packaged resources loaded

/ready returns 200 only when both clients_ready and resources_ready are true. It does not contact Kubernetes or other APIs, so it is not a live dependency check. A missing packaged resource Markdown file keeps /ready at 503 even though /health and registered tools remain available; check the server logs and package contents rather than cluster dependencies.

Environment variables

Variable	Default	Description
`MCP_TRANSPORT`	`stdio`	Transport protocol (`http`, `sse`, `stdio`)
`KUBEFLOW_MCP_AUTH_TOKEN`	(none)	Bearer token for HTTP auth
`KUBEFLOW_MCP_JWKS_URI`	(none)	JWKS endpoint for JWT verification (production)
`KUBEFLOW_MCP_JWT_ISSUER`	(none)	Expected JWT issuer
`KUBEFLOW_MCP_JWT_AUDIENCE`	(none)	Expected JWT audience
`KUBEFLOW_MCP_CLIENTS`	`trainer`	Comma-separated client modules to load
`KUBEFLOW_MCP_PERSONA`	`readonly`	Tool persona (`readonly`, `data-scientist`, `ml-engineer`, `platform-admin`)
`KUBEFLOW_MCP_INSTRUCTION_TIER`	`full`	Instruction verbosity (`full`, `compact`, `minimal`)
`KUBEFLOW_MCP_ALLOWED_HOSTS`	(loopback)	Comma-separated `Host` header allowlist for DNS rebinding protection; `:` port wildcard supported (e.g. `mcp.example.com,mcp.example.com:`)
`KUBEFLOW_MCP_ALLOWED_ORIGINS`	(loopback)	Comma-separated `Origin` header allowlist; `:*` port wildcard supported (e.g. `https://mcp.example.com`)
`KUBEFLOW_MCP_DNS_REBINDING_PROTECTION`	`true`	Set `false` to disable Host/Origin validation (not recommended)
`LOG_FORMAT`	(auto)	Log format (`json`, `console`); defaults to `console` in an interactive terminal and `json` otherwise
`LOG_LEVEL`	`INFO`	Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)

MCP client config (HTTP transport)

{
  "mcpServers": {
    "kubeflow": {
      "url": "http://localhost:8000/mcp",
      "headers": { "Authorization": "Bearer my-secret-token" }
    }
  }
}

For in-cluster deployments, replace localhost:8000 with the Kubernetes Service address and mount KUBEFLOW_MCP_AUTH_TOKEN from a Secret.

Note: DNS rebinding protection allows only loopback Host/Origin headers by default. When exposing the server through a Service or Ingress, set KUBEFLOW_MCP_ALLOWED_HOSTS (e.g. KUBEFLOW_MCP_ALLOWED_HOSTS=kubeflow-mcp.kubeflow.svc:*,mcp.example.com) or requests will be rejected with HTTP 421.

Example: Fine-tune a model via AI agent

Once connected, your AI agent can run a complete training workflow through natural language:

User: "Fine-tune gemma-2b on the alpaca dataset"

Agent calls: check_compatibility()        → ✅ K8s 1.29, Trainer CRD installed
Agent calls: get_cluster_resources()      → 4x A100 GPUs available
Agent calls: estimate_resources("google/gemma-2b") → needs ~16GB GPU, 1x A100
Agent calls: list_runtimes()              → torchtune-llama, torchtune-gemma, ...
Agent calls: fine_tune(                   → preview config (confirmed=False)
    model="hf://google/gemma-2b",
    dataset="hf://tatsu-lab/alpaca",
    runtime="torchtune-gemma-2b"
)
Agent calls: fine_tune(..., confirmed=True) → TrainJob "train-gemma-abc" created
Agent calls: get_training_logs("train-gemma-abc") → training progress...

Most mutating tools require confirmed=True and return a preview before making changes. update_training_job is a legacy exception and immediately suspends or resumes a training job.

MCP Client Config

Cursor

Add to .cursor/mcp.json (or use the .mcp.json at the repo root for local dev):

{
  "mcpServers": {
    "kubeflow": {
      "command": "uv",
      "args": ["run", "kubeflow-mcp", "serve"]
    }
  }
}

Claude Code

claude mcp add kubeflow -- kubeflow-mcp serve

Tools

23 tools organized by workflow phase:

Phase	Tools	Description
Planning	`pre_flight`, `check_compatibility`, `get_cluster_resources`, `estimate_resources`	Environment validation and resource estimation
Discovery	`list_training_jobs`, `get_training_job`, `list_runtimes`, `get_runtime`	Browse jobs and available runtimes
Training	`fine_tune`, `run_custom_training`, `run_container_training`	Submit LoRA/QLoRA fine-tuning, custom scripts, or container jobs
Monitoring	`get_training_logs`, `get_training_events`, `wait_for_training`	Track progress, debug failures
Lifecycle	`delete_training_job`, `update_training_job`	Manage existing jobs (ownership-guarded)
Platform	`inspect_crd`, `inspect_controller`, `patch_runtime`, `create_runtime`, `delete_runtime`	Cluster inspection and runtime management
Health	`health_check`, `get_server_logs`	Server diagnostics

Requirements

MCP Server	Kubeflow Trainer	Kubeflow SDK	Python	Kubernetes
0.1.x	>= 2.2.0	>= 0.4.0	3.10 - 3.12	>= 1.27

CLI Reference