Kubeflow MCP

Servidor MCP de Kubeflow

Propuesta: KEP-936 · HOJA DE RUTA · SEGURIDAD · CONTRIBUCIÓN

Descripción general

El Servidor MCP de Kubeflow expone las operaciones de entrenamiento de Kubeflow como herramientas del Protocolo de Contexto de Modelo, lo que permite a los agentes de IA (Claude, Cursor, Claude Code o cualquier agente personalizado, etc.) planificar, enviar, monitorear y gestionar trabajos de entrenamiento mediante lenguaje natural, sin que los usuarios necesiten aprender Kubernetes o el SDK de Kubeflow directamente.

Beneficios

• Nativo para agentes: Herramientas autodetectables mediante MCP, sin necesidad de conexión manual de API
• Flujo de trabajo guiado: Ordenamiento por fases con sugerencias de siguientes pasos (Planificar → Descubrir → Entrenar → Monitorear)
• Vista previa antes de enviar: Cada operación de modificación requiere confirmación explícita
• Seguridad primero: Control de personas, aplicación de espacios de nombres, validación de entrada, autenticación bearer/JWT
• Multiplataforma: Detecta automáticamente OpenShift, EKS, GKE con orientación específica por plataforma
• Eficiente en tokens: Los modos progresivo/semántico comprimen 23 herramientas en 2-3 metaherramientas
• Extensible: Arquitectura de complementos para clientes adicionales de Kubeflow (TODO: optimizador, hub)

Demostración

Comenzar

Instalar desde PyPI

pip install kubeflow-mcp

Instalar desde el código fuente (desarrollo)

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

Requisitos previos

Antes de iniciar el Servidor MCP de Kubeflow, asegúrate de que los siguientes requisitos estén disponibles:

• Python 3.10, 3.11 o 3.12
• Un clúster de Kubernetes en ejecución
• kubectl instalado y disponible en PATH
• Un kubeconfig configurado para el clúster de destino
• Kubeflow Trainer instalado en el clúster
• CRDs de Kubeflow Trainer y al menos un ClusterTrainingRuntime
• Permisos de Kubernetes para el espacio de nombres donde entrenas, además de acceso de lectura a nivel de clúster para la planificación y el descubrimiento en tiempo de ejecución (consulta Configuración de RBAC)

Verifica la conexión y tus permisos en el espacio de nombres de destino. Cada comando can-i debería imprimir yes:

kubectl config current-context
kubectl auth can-i create trainjobs.trainer.kubeflow.org -n <namespace>
kubectl auth can-i list pods -n <namespace>
kubectl auth can-i get pods --subresource=log -n <namespace>

Las comprobaciones siguientes necesitan acceso de lectura a nivel de clúster, por lo que pueden devolver Forbidden para un usuario limitado al espacio de nombres incluso cuando Kubeflow Trainer está instalado correctamente. Sin ese acceso, las herramientas que leen estos recursos (get_cluster_resources, check_compatibility, list_runtimes) fallarán; las herramientas que trabajan con trabajos en tu espacio de nombres no se ven afectadas.

kubectl get nodes
kubectl get crd trainjobs.trainer.kubeflow.org
kubectl get clustertrainingruntimes

Ejecutar el servidor

kubeflow-mcp serve

Ejecutar con Docker

Las imágenes multiarquitectura precompiladas se publican en GHCR en cada versión:

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

El servidor escucha en http://localhost:8000/mcp.

Los sondeos de contenedor y Kubernetes están disponibles sin autenticación MCP:

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

/ready devuelve 200 solo cuando tanto clients_ready como resources_ready son verdaderos. No se comunica con Kubernetes ni con otras API, por lo que no es una comprobación de dependencia en vivo. Un archivo Markdown de recursos empaquetado faltante mantiene /ready en 503 aunque /health y las herramientas registradas sigan disponibles; revisa los registros del servidor y el contenido del paquete en lugar de las dependencias del clúster.

Variables de entorno

Configuración del cliente MCP (transporte HTTP)

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

Para implementaciones dentro del clúster, reemplaza localhost:8000 con la dirección del Servicio de Kubernetes y monta KUBEFLOW_MCP_AUTH_TOKEN desde un Secreto.

Nota: La protección contra reenlace de DNS solo permite encabezados Host/Origin de bucle local de forma predeterminada. Al exponer el servidor mediante un Servicio o Ingress, establece KUBEFLOW_MCP_ALLOWED_HOSTS (p. ej., KUBEFLOW_MCP_ALLOWED_HOSTS=kubeflow-mcp.kubeflow.svc:*,mcp.example.com) o las solicitudes se rechazarán con HTTP 421.

Ejemplo: Ajuste fino de un modelo mediante un agente de IA

Una vez conectado, tu agente de IA puede ejecutar un flujo de trabajo de entrenamiento completo mediante lenguaje natural:

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...

Todas las herramientas de modificación requieren confirmed=True y devuelven una vista previa antes de realizar cambios.

Configuración del cliente MCP

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

claude mcp add kubeflow -- kubeflow-mcp serve

Herramientas

23 herramientas organizadas por fase del flujo de trabajo:

Requisitos

Referencia de CLI

kubeflow-mcp serve

# Modules: trainer, optimizer (stub), hub (stub)
# Persona: readonly | data-scientist | ml-engineer | platform-admin
# Mode: full | progressive | semantic
# Instruction tier: full | compact | minimal
# Transport: stdio | http | sse (deprecated)
# Auth token: bearer token for HTTP auth (dev/staging)
# OTel endpoint: optional OTLP HTTP endpoint for tracing
# Log level: DEBUG | INFO | WARNING | ERROR
# Log format: console | json (auto-detected if omitted)
# No banner: suppress the FastMCP startup banner
kubeflow-mcp serve \
  --clients trainer \
  --persona ml-engineer \
  --mode full \
  --instruction-tier full \
  --transport stdio \
  --auth-token SECRET \
  --otel-endpoint URL \
  --log-level INFO \
  --log-format console \
  --no-banner

--mode progressive expone 3 metaherramientas (~85 tokens) para descubrimiento jerárquico. --mode semantic expone 2 metaherramientas (~69 tokens) mediante búsqueda por incrustaciones. Ambas reducen significativamente el consumo de tokens para flujos de trabajo de agentes.

--persona controla qué herramientas se exponen. Cada persona incluye las herramientas de la que está por encima:

# Simple API key (dev/staging)
kubeflow-mcp serve --transport http --auth-token my-secret-token

# Or via env var
export KUBEFLOW_MCP_AUTH_TOKEN=my-secret-token
kubeflow-mcp serve --transport http

# JWT verification (production)
export KUBEFLOW_MCP_JWKS_URI=https://auth.example.com/.well-known/jwks.json
export KUBEFLOW_MCP_JWT_ISSUER=https://auth.example.com
export KUBEFLOW_MCP_JWT_AUDIENCE=kubeflow-mcp
kubeflow-mcp serve --transport http

Observabilidad

El rastreo de OpenTelemetry es opcional y se puede habilitar sin cambiar el código de las herramientas.

• Instala dependencias opcionales desde el código fuente: uv sync --group otel
• Habilita el rastreo con la bandera de CLI o la variable de entorno:

kubeflow-mcp serve --otel-endpoint http://localhost:4318
# or
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
kubeflow-mcp serve

Cada invocación de herramienta emite un tramo con atributos: tool.name, tool.args_preview, tool.success, tool.duration_ms, kubeflow.persona y correlation_id.

Desarrollo

make install-dev                  # setup environment
make verify                       # lint + format check
make test-python                  # run tests
make inspector                    # launch MCP Inspector (stdio)
make inspector TRANSPORT=http     # Inspector + Streamable HTTP (start server separately)
make inspector TRANSPORT=sse      # Inspector + SSE (deprecated; start server separately)

Comunidad

• Slack: Únete a #kubeflow-ml-experience en CNCF Slack
• Reuniones: Asiste a la llamada quincenal de SDK de Kubeflow y Experiencia de ML
• GitHub: Problemas y contribuciones en kubeflow/mcp-server

Documentación

• CONTRIBUCIÓN: Flujo de trabajo de desarrollo y pautas para PR
• HOJA DE RUTA: Hoja de ruta del proyecto
• SEGURIDAD: Reporte de vulnerabilidades; consulta ARCHITECTURE.md#security-model para el modelo de amenazas, RBAC y endurecimiento
• Convenciones de clientes: Lista de verificación para agregar módulos de cliente
• KEP-936: Propuesta de diseño

Licencia

Licencia Apache 2.0 — consulta LICENCIA.