churn-mcp-server

Expone la API de predicción de churn de ml-production-template como una herramienta MCP, de modo que un cliente compatible con MCP (Claude Desktop, Claude Code, o cualquier cliente MCP) pueda llamar a predict_churn directamente.

Diseño

Es un adaptador ligero, no una reescritura del servidor de modelos. No carga el modelo por sí mismo: llama al endpoint /predict del servicio churn-api ya desplegado, a través de HTTP. Eso significa que:

• La capa MCP se puede redesplegar o escalar de forma independiente del modelo.

• Si churn-api se reinicia, esta capa no necesita hacerlo.

• El sistema ML "real" (FastAPI + MLflow) no se toca; MCP es una interfaz aditiva encima de él, lo que coincides con cómo integrarías MCP en un servicio de producción existente en lugar de incrustarlo en el servidor de modelos.

Se exponen dos herramientas:

• predict_churn: el esquema del cliente de 19 campos de la API real, que devuelve churn_probability / churn_prediction / threshold_used.

• check_model_health: funciona como proxy del endpoint /health de la API.

Related MCP server: MCP from API

Nota sobre la versión

El SDK oficial de Python mcp publicó recientemente una v2.0 que renombró FastMCP como MCPServer y movió las rutas de importación. Este proyecto fija la dependencia en mcp<2.0.0 y usa from mcp.server.fastmcp import FastMCP, ya que esa sigue siendo la versión estable y ampliamente documentada en el momento de escribir esto. Si estás leyendo esto más adelante y pip install mcp instala la v2 por defecto, tendrás que migrar la importación (mcp.server.fastmcp.FastMCP → mcp.server.MCPServer); consulta la guía de migración del SDK antes de asumir que el código siguiente sigue siendo válido tal cual.

Prueba local (stdio, sin Docker)

pip install -r requirements.txt
$env:MCP_TRANSPORT="stdio"
$env:CHURN_API_URL="http://localhost:8000"   # your local churn-api
python server.py

Apunta el claude_desktop_config.json de Claude Desktop al servidor:

{
  "mcpServers": {
    "churn-predictor": {
      "command": "python",
      "args": ["C:\\path\\to\\churn-mcp-server\\server.py"],
      "env": { "CHURN_API_URL": "http://localhost:8000" }
    }
  }
}

Despliegue en el clúster kind existente

Esto asume que el Deployment y el Service de churn-api del proyecto de Kubernetes ya se están ejecutando en tu clúster kind.

docker build -t churn-mcp-server:local .
kind load docker-image churn-mcp-server:local --name <your-cluster-name>
kubectl apply -f k8s/deployment.yaml
kubectl get pods -l app=churn-mcp-server

Verifica:

kubectl port-forward svc/churn-mcp-server 8080:80
curl http://localhost:8080/healthz

Un detalle real que conviene conocer de cara a entrevistas

Un GET /mcp sin más devuelve 406 Not Acceptable: el transporte streamable-http de MCP requiere Accept: text/event-stream, y una sonda httpGet simple de Kubernetes no envía ese encabezado. Eso rompe una sonda de preparación ingenua que apunte directamente a /mcp. La solución aquí: FastMCP.streamable_http_app() devuelve la aplicación Starlette subyacente, que puedes montar junto con una ruta /healthz escrita a mano que devuelve un simple 200; consulta el final de server.py. Esta es una historia legítima de "me encontré con un problema real de integración y entendí el porqué", algo que ofrece una respuesta de entrevista más sólida que un proyecto en el que no salió nada mal.

Lo que esto demuestra (frase precisa para el currículum)

"Construí un servidor MCP que expone un endpoint de FastAPI para servir modelos como una herramienta invocable, desplegado en Kubernetes junto al servicio existente."

No es exacto: incluir "MCP" como una mera etiqueta de habilidad sin de poder explicar qué es MCP en realidad (un protocolo para exponer herramientas a clientes LLM, no un mecanismo de despliegue ni de alojamiento).