Kubeflow MCP

Servidor Kubeflow MCP

Proposta: KEP-936 · ROADMAP · SEGURANÇA · CONTRIBUIÇÃO

Visão Geral

O Servidor Kubeflow MCP expõe operações de Treinamento Kubeflow como ferramentas do Model Context Protocol, permitindo que agentes de IA (Claude, Cursor, Claude Code, ou qualquer agente personalizado, etc.) planejem, submetam, monitorem e gerenciem trabalhos de treinamento por meio de linguagem natural — sem que os usuários precisem aprender Kubernetes ou o SDK Kubeflow diretamente.

Benefícios

• Nativo para Agentes: Ferramentas descobertas automaticamente via MCP — sem necessidade de integração manual de API
• Fluxo de Trabalho Guiado: Ordenação de fases com dicas de próximos passos (Planejar → Descobrir → Treinar → Monitorar)
• Pré-visualização Antes da Submissão: Toda operação de mutação exige confirmação explícita
• Segurança em Primeiro Lugar: Controle de persona, aplicação de namespace, validação de entrada, autenticação bearer/JWT
• Multi-plataforma: Detecta automaticamente OpenShift, EKS, GKE com orientação específica da plataforma
• Eficiente em Tokens: Modos progressivo/semântico comprimem 23 ferramentas em 2-3 meta-ferramentas
• Extensível: Arquitetura de plugins para clientes Kubeflow adicionais (TODO: otimizador, hub)

Demonstração

Comece Aqui

Instalar a partir do PyPI

pip install kubeflow-mcp

Instalar a partir do código-fonte (desenvolvimento)

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

Pré-requisitos

Antes de iniciar o Servidor Kubeflow MCP, certifique-se de que os seguintes requisitos estejam disponíveis:

• Python 3.10, 3.11 ou 3.12
• Um cluster Kubernetes em execução
• kubectl instalado e disponível em PATH
• Um kubeconfig configurado para o cluster de destino
• Kubeflow Trainer instalado no cluster
• CRDs do Kubeflow Trainer e pelo menos um ClusterTrainingRuntime
• Permissões Kubernetes para o namespace em que você treina, além de acesso de leitura no escopo do cluster para planejamento e descoberta de runtime (consulte Configuração RBAC)

Verifique a conexão e suas permissões no namespace de destino. Cada comando can-i deve 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>

As verificações abaixo precisam de acesso de leitura no escopo do cluster, portanto podem retornar Forbidden para um usuário com escopo de namespace mesmo quando o Kubeflow Trainer está instalado corretamente. Sem esse acesso, as ferramentas que leem esses recursos (get_cluster_resources, check_compatibility, list_runtimes) falham; as ferramentas que trabalham em trabalhos no seu namespace não são afetadas.

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

Executar o servidor

kubeflow-mcp serve

Executar com Docker

Imagens multi-arquitetura pré-construídas são publicadas no GHCR a cada lançamento:

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

O servidor escuta em http://localhost:8000/mcp.

Sondas de contêiner e Kubernetes estão disponíveis sem autenticação MCP:

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

/ready retorna 200 somente quando ambos clients_ready e resources_ready são verdadeiros. Ele não entra em contato com Kubernetes ou outras APIs, portanto não é uma verificação de dependência ativa. Um arquivo Markdown de recurso empacotado ausente mantém /ready em 503 mesmo que /health e as ferramentas registradas permaneçam disponíveis; verifique os logs do servidor e o conteúdo do pacote em vez das dependências do cluster.

Variáveis de ambiente

Configuração do cliente MCP (transporte HTTP)

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

Para implantações dentro do cluster, substitua localhost:8000 pelo endereço do Serviço Kubernetes e monte KUBEFLOW_MCP_AUTH_TOKEN a partir de um Secret.

Nota: A proteção contra rebinding de DNS permite apenas cabeçalhos Host/Origin de loopback por padrão. Ao expor o servidor por meio de um Service ou Ingress, defina KUBEFLOW_MCP_ALLOWED_HOSTS (ex.: KUBEFLOW_MCP_ALLOWED_HOSTS=kubeflow-mcp.kubeflow.svc:*,mcp.example.com) ou as solicitações serão rejeitadas com HTTP 421.

Exemplo: Ajuste fino de um modelo via agente de IA

Uma vez conectado, seu agente de IA pode executar um fluxo de trabalho completo de treinamento por meio de linguagem 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 as ferramentas de mutação exigem confirmed=True e retornam uma pré-visualização antes de fazer alterações.

Configuração do Cliente MCP

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

claude mcp add kubeflow -- kubeflow-mcp serve

Ferramentas

23 ferramentas organizadas por fase do fluxo de trabalho:

Requisitos

Referência da 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 expõe 3 meta-ferramentas (~85 tokens) para descoberta hierárquica. --mode semantic expõe 2 meta-ferramentas (~69 tokens) usando busca por incorporação. Ambos reduzem significativamente o consumo de tokens para fluxos de trabalho de agentes.

--persona controla quais ferramentas são expostas. Cada persona inclui as ferramentas da anterior:

# 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

Observabilidade

O rastreamento OpenTelemetry é opcional e pode ser habilitado sem alterar o código das ferramentas.

• Instale dependências opcionais a partir do código-fonte: uv sync --group otel
• Habilite o rastreamento com flag da CLI ou variável de ambiente:

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

Cada invocação de ferramenta emite um span com atributos: tool.name, tool.args_preview, tool.success, tool.duration_ms, kubeflow.persona e correlation_id.

Desenvolvimento

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)

Comunidade

• Slack: Participe do #kubeflow-ml-experience no CNCF Slack
• Reuniões: Participe da chamada quinzenal do Kubeflow SDK and ML Experience
• GitHub: Problemas e contribuições em kubeflow/mcp-server

Documentação

• CONTRIBUIÇÃO: Fluxo de trabalho de desenvolvimento e diretrizes de PR
• ROADMAP: Roadmap do projeto
• SEGURANÇA: Relato de vulnerabilidades; consulte ARCHITECTURE.md#security-model para modelo de ameaças, RBAC e endurecimento
• Convenções de cliente: Lista de verificação para adicionar módulos de cliente
• KEP-936: Proposta de design

Licença

Apache License 2.0 — consulte LICENSE.