churn-mcp-server

将现有的 ml-production-template 客户流失预测 API 暴露为 MCP 工具，使支持 MCP 的客户端（Claude Desktop、Claude Code 或任何 MCP 客户端）可以直接调用 predict_churn。

设计

这是一个轻量适配器，而不是对模型服务器的重写。它本身不加载模型，而是通过 HTTP 调用已部署的 churn-api 服务的 /predict 端点。这意味着：

• MCP 层可以独立于模型重新部署或伸缩。

• 如果 churn-api 重启，此层无需随之重启。

• 真正的 ML 系统（FastAPI + MLflow）不会受影响；MCP 是叠加在其之上的附加接口，这与你实际将 MCP 集成到现有生产服务的方式一致，而不是把它内嵌到模型服务器中。

暴露了两个工具：

• predict_churn —— 与真实 API 相同的 19 字段客户端 schema，返回 churn_probability / churn_prediction / threshold_used。

• check_model_health —— 代理 API 的 /health 端点。

Related MCP server: MCP from API

版本说明

官方 mcp Python SDK 最近发布了 v2.0，将 FastMCP 重命名为 MCPServer，并调整了导入路径。本服务固定使用 mcp<2.0.0，并采用 from mcp.server.fastmcp import FastMCP，因为截至撰写本文时，这仍是稳定且文档齐全的版本。如果你在以后读到这些内容，并且 pip install mcp 默认拉取 v2，则需要迁移导入语句（mcp.server.fastmcp.FastMCP → mcp.server.MCPServer）——在假设以下代码仍然适用之前，请先查阅 SDK 的迁移指南。

本地测试（stdio，无需 Docker）

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

将 Claude Desktop 的 claude_desktop_config.json 指向它：

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

部署到现有 kind 集群

这里假定 Kubernetes 项目中的 churn-api Deployment 和 Service 已经在你 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

验证：

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

一个面试中值得知道的真实坑

纯 GET /mcp 返回 406 Not Acceptable——MCP 的 streamable-http 传输要求 Accept: text/event-stream，而普通的 Kubernetes httpGet 探针不会发送这样的请求头。这会破坏直接指向 /mcp 的简单就绪探针。这里的解决办法是：FastMCP.streamable_http_app() 会返回底层 Starlette 应用，你可以把它和手写的 /healthz 路由一起挂载，该路由返回一个普通 200——参见 server.py 底部。这是一个真实的“我碰到了实际集成问题并理解了原因”的故事，比一个完全没出过问题的项目是更有力的面试回答。

这段经历展示的能力（准确的简历说法）

“构建了一个 MCP 服务器，将生产环境中 FastAPI 模型的对外服务端点暴露为可调用工具，并与现有服务一起部署到 Kubernetes。”

不准确的表述：把“MCP”当作一个裸技能标签，却无法解释 MCP 到底是什么（MCP 是向 LLM 客户端暴露工具的一种协议，而不是部署或托管机制）。