churn-mcp-server

既存の ml-production-template のチャーン予測 API を MCP ツールとして公開し、MCP 対応クライアント（Claude Desktop、Claude Code、その他の MCP クライアント）から predict_churn を直接呼び出せるようにします。

設計

これは薄いアダプタであり、モデルサーバーの書き直しではありません。モデル自体はロードせず、すでにデプロイ済みの churn-api サービスの /predict エンドポイントを HTTP 経由で呼び出します。つまり:

• MCP レイヤーはモデルとは独立に再デプロイ・スケーリングできます。

• churn-api が再起動しても、この MCP レイヤーを再起動する必要はありません。

• 「実際の」ML システム（FastAPI + MLflow）はそのままです。MCP はその上に付加されるインターフェースであり、モデルサーバーに組み込むのではなく、既存の本番サービスに MCP を統合する実際の方法に沿っています。

公開されるツールは 2 つです:

• predict_churn -- 実 API の 19 フィールドから成る顧客スキーマを受け取り、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 を直接指した単純な readiness プローブは壊れます。ここでの修正方法は、FastMCP.streamable_http_app() が内部の Starlette アプリを返すことを利用して、手書きの /healthz ルート（素の 200 を返す）と一緒にマウントすることです。詳細は server.py の末尾を参照してください。これは「実際の統合問題にぶつかり、その理由を理解した」という正当なエピソードであり、何も問題が起きなかったプロジェクトより面接での回答として強くなります。

これが示すこと（履歴書に載せる正しい表現）

「本番の FastAPI モデル提供エンドポイントを呼び出し可能なツールとして公開する MCP サーバーを構築し、既存のサービスと並べて Kubernetes にデプロイした。」

不正確な表現: 「MCP」という素のスキルタグを挙げるだけで、MCP が実際に何であるか（LLM クライアントに対してツールを公開するためのプロトコルであり、デプロイやホスティングの仕組みではない）を説明できないこと。