churn-mcp-server

기존 ml-production-template churn-prediction API를 MCP 도구로 노출하므로, MCP를 인식하는 클라이언트(Claude Desktop, Claude Code 또는 모든 MCP 클라이언트)가 predict_churn을 직접 호출할 수 있습니다.

설계

이 프로젝트는 모델 서버를 다시 작성한 것이 아니라 가벼운 어댑터입니다. 모델 자체를 로드하지 않고, 이미 배포된 churn-api 서비스의 /predict 엔드포인트를 HTTP로 호출합니다. 즉:

• MCP 계층은 모델과 독립적으로 재배포하거나 확장할 수 있습니다.

• churn-api가 재시작되어도 이 어댑터는 재시작할 필요가 없습니다.

• "실제" ML 시스템(FastAPI + MLflow)은 그대로 유지됩니다. MCP는 모델 서버에 내장되는 대신 기존 프로덕션 서비스 위에 추가되는 인터페이스이며, 기존 서비스에 MCP를 실제로 통합하는 방식과 일치합니다.

두 개의 도구가 노출됩니다.

• 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로 이름을 바꾸고 import 경로를 이동했습니다. 이 프로젝트는 mcp<2.0.0으로 고정하고 from mcp.server.fastmcp import FastMCP를 사용하는데, 현재 기준으로도 이 버전이 안정적이고 널리 문서화된 라인이기 때문입니다. 나중에 이 글을 읽고 있다면 pip install mcp가 기본적으로 v2를 가져올 수 있으므로 import 경로를 이식(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 프로브는 이 헤더를 보내지 않기 때문입니다. 여기서 사용한 해결책은 FastMCP.streamable_http_app()이 기본 Starlette 앱을 반환한다는 점을 이용해, 200을 반환하는 직접 작성한 /healthz 라우트와 함께 마운트하는 것입니다. server.py의 하단을 참고하세요. 이것은 "실제 통합 문제를 만났고 그 이유를 이해했다"는 진짜 경험 이야기이며, 아무 문제가 없었던 프로젝트보다 면접에서 훨씬 강한 답변이 됩니다.

이것이 보여주는 것(정확한 이력서 표현)

"프로덕션 FastAPI 모델 서빙 엔드포인트를 호출 가능한 도구로 노출하는 MCP 서버를 구축하고, 기존 서비스와 함께 Kubernetes에 배포했습니다."

정확하지 않은 표현: MCP가 실제로 무엇인지(LLM 클라이언트에 도구를 노출하기 위한 프로토콜이지, 배포나 호스팅 메커니즘이 아님) 설명할 수 없는 상태에서 "MCP"를 단순한 기술 태그로 쓰는 것입니다.