Credit Risk MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Credit Risk MCP Server Score a borrower earning $60k who wants a $300k loan and explain the top risk factors."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Credit Risk MCP Server
An MCP (Model Context Protocol) server that exposes a trained Home Credit Default Risk model as tools any Claude client can call in plain conversation — score a borrower, explain the prediction with SHAP, compare applicants, and query the model's metadata.
It wraps the XGBoost model from my home-credit-default project and serves it two ways: locally over stdio (for Claude Desktop / Claude Code) and remotely over HTTP with API-key authentication (so any MCP client can reach it).
⚠️ Educational project. The model is trained on a public Kaggle dataset and is not a real lending-decision system. Do not use it to make credit decisions about real people.
What it does
Describe a loan applicant in plain terms and Claude will call the right tool:
Tool | What it returns |
| Default probability (0–1), a risk tier, and a decision flag at the recall-oriented 0.15 threshold |
| The top factors pushing risk up or down for one applicant, via SHAP, with human-readable names |
| Model type, AUC, precision/recall at different thresholds, and limitations |
| The model's globally most important features (mean |SHAP|) |
| Several applicants scored and ranked from most to least risky |
The interesting engineering problem: the model expects a 235-column encoded vector, but a person can only describe ~10 things about a borrower. The server starts from training-set medians and overlays the fields the user actually provides — replicating the notebook's exact encodings and engineered features — so a handful of plain inputs become a valid model row. It also reports which fields fell back to defaults, so the estimate's confidence stays transparent.
Related MCP server: MCP Unified Server
Architecture
flowchart LR
Client["Claude client<br/>(Desktop / Code / any MCP client)"] -->|stdio or HTTP+Bearer| Server
subgraph Server["MCP server (FastMCP)"]
Tools["tool layer<br/>server.py"] --> Service["model_service.py<br/>build_feature_vector · score · explain"]
end
Service --> Artifacts["artifacts/<br/>model.json · feature columns · medians · SHAP importance"]The model and its supporting data are exported once into small, portable JSON
artifacts (artifacts/), so the server has no dependency on the original 362 MB
training CSV at run time.
Quickstart (local)
Requires uv.
uv sync
uv run --extra dev pytest -q # 24 tests
uv run python -m credit_risk_mcp.server # runs over stdio (waits for a client)See Connecting an MCP client below to wire it into Claude or any other MCP-capable app.
Remote (HTTP + auth)
Over HTTP the server requires a bearer key on every request, so it's safe to expose. Set the secret and run:
export CREDIT_RISK_API_KEY="$(uv run python -c 'import secrets; print(secrets.token_urlsafe(32))')"
uv run credit-risk-httpThe MCP endpoint is served at /mcp; a public /health route is left open for
platform health checks. Requests without a valid Authorization: Bearer <key>
header get 401. A Dockerfile and render.yaml are included for one-click
deployment to Render (or any Docker host): the platform injects $PORT and you
provide CREDIT_RISK_API_KEY as a secret. MCP_ALLOWED_HOSTS (comma-separated)
optionally restricts which Host headers are accepted; by default any host is
allowed and the bearer key is the sole gate.
Connecting an MCP client
The server speaks the standard MCP protocol, so any MCP-capable client can use
it. You need the /mcp URL and the API key. In the examples below, replace
YOUR-APP with your deployment's host and YOUR_KEY with its
CREDIT_RISK_API_KEY (deploy your own with the render.yaml above to get a key
of your own).
Claude Code (CLI)
Remote server over HTTP:
claude mcp add --transport http credit-risk https://YOUR-APP.onrender.com/mcp --header "Authorization: Bearer YOUR_KEY"…or run a local copy over stdio (no key needed):
claude mcp add credit-risk -s user -- uv --directory /ABSOLUTE/PATH/TO/credit-risk-mcp run python -m credit_risk_mcp.serverThen claude mcp list should show it connected. Start a new session and ask:
"Using credit-risk, score a borrower earning $60k who wants a $300k loan, and
explain the top factors."
Claude Desktop (and other stdio-only clients)
Bridge the remote server with mcp-remote.
In Claude Desktop, open Settings → Developer → Edit Config and add:
{
"mcpServers": {
"credit-risk": {
"command": "npx",
"args": [
"mcp-remote",
"https://YOUR-APP.onrender.com/mcp",
"--header",
"Authorization: Bearer YOUR_KEY"
]
}
}
}Fully restart Claude Desktop; the tools appear behind the tools/plug icon.
Any other MCP client
Point it at the Streamable HTTP endpoint https://YOUR-APP.onrender.com/mcp and
send Authorization: Bearer YOUR_KEY with each request. Clients that support
only stdio can use the mcp-remote bridge shown above.
Inspect the tools directly
# remote: run the Inspector, then choose "Streamable HTTP", enter the /mcp URL,
# and add an "Authorization: Bearer YOUR_KEY" header
npx @modelcontextprotocol/inspector
# local stdio:
npx @modelcontextprotocol/inspector uv run python -m credit_risk_mcp.serverNote: free hosting tiers sleep when idle, so the first request after a pause can take 30–60 s to wake the server.
About the model
Model: XGBoost classifier (100 trees, max depth 5), 235 features, trained on ~308k applications from the Kaggle Home Credit Default Risk dataset (SMOTE-balanced for the ~92%/8% class imbalance).
Performance: AUC-ROC ≈ 0.75.
Threshold: predictions use a 0.15 decision threshold rather than 0.5. In credit risk a missed defaulter (lost principal) costs far more than a false alarm, so the model is tuned for recall (~0.47 recall / ~0.21 precision at 0.15).
What drives it: external credit-bureau scores (
EXT_SOURCE_1/2/3) dominate, followed by employment type and demographics.
Tech stack
Python · MCP Python SDK (FastMCP) · XGBoost · SHAP · pandas · Pydantic · Starlette/Uvicorn (HTTP) · Docker · uv.
Available Tools
5 toolscompare_borrowersA
Score several applicants at once and rank them from most to least risky.
Use this to compare a batch of borrowers side by side. Each profile is scored exactly like score_borrower.
Args: profiles: two or more applicants to compare.
Returns {"ranked": [...]} sorted by default_probability descending. Each entry has: rank (1 = riskiest), index (position in the input list), default_probability, and risk_tier.
Educational model — not real lending advice.
Inputs: profiles (required). Returns: object
explain_predictionA
Explain a default-risk prediction: which factors push risk up or down.
Use this when the user wants the "why" behind a score, not just the number. Runs SHAP on the single applicant and returns the strongest contributing features with human-readable names.
Args: profile: the applicant to explain. top_n: how many contributing factors to return (default 8).
Returns a dict with default_probability, risk_tier, and top_factors — a list of {feature, friendly_name, value, shap_contribution, direction} ordered by impact, where direction is "increases risk" or "decreases risk".
Educational model — not real lending advice.
Inputs: profile (required), top_n. Returns: object
get_feature_importanceA
Return the model's globally most important features (by mean |SHAP|).
Use this for "what drives this model overall?" questions, as opposed to the reasons behind one borrower's score. Returns {"top_features": [...]} ranked by average absolute SHAP impact across a sample, each entry carrying its raw name, a friendly name, and its importance score.
Args: top_n: how many features to return (default 10).
Inputs: top_n. Returns: object
get_model_infoA
Describe the model itself: type, performance, and limitations.
Use this to answer questions about how good the model is or how it should be used — no borrower needed. Returns model type, feature count, training size, AUC-ROC, precision/recall at the 0.50 and 0.15 thresholds, the recommended threshold, and an honest limitations note (educational, not real lending advice).
Inputs: no named parameters. Returns: object
score_borrowerA
Estimate a loan applicant's probability of default.
Use this to get a single risk number for one borrower. Describe the applicant in plain terms — only annual income and loan amount are required; every other field falls back to the population median when omitted.
Returns a dict with:
default_probability: estimated probability of default (0-1)
risk_tier: "low" / "moderate" / "elevated" / "high"
flag_default: True if the probability is at or above the 0.15 decision threshold (this model is tuned for recall, not a 50% cutoff)
threshold_used: the decision threshold (0.15)
fields_defaulted: which optional fields fell back to medians
Educational model trained on a Kaggle dataset — not real lending advice.
Inputs: profile (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct purpose: score_borrower (single), compare_borrowers (batch ranking), explain_prediction (local SHAP), get_feature_importance (global SHAP), and get_model_info (metadata). The descriptions explicitly contrast overlapping-sounding pairs like global feature importance vs per-borrower explanation, leaving no realistic selection ambiguity.
All five names follow a clean verb_noun snake_case pattern (get_feature_importance, compare_borrowers, get_model_info, score_borrower, explain_prediction). The verbs are apt and used consistently with no mixing of conventions.
Five tools is a well-scoped set for a model-inference domain, with each tool earning a distinct role (score, compare, explain, global importance, metadata). Nothing is redundant or missing for the apparent purpose.
The surface fully covers the inference lifecycle: single scoring, batch comparison, per-prediction explanation, global feature importance, and model metadata/limitations. As a stateless scoring service there are no CRUD gaps, and the tools form a coherent complete workflow.
Maintenance
Related MCP Connectors
Build and manage AI-native customer support agents from Claude or any MCP client.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Deploy and share tools built with Claude or ChatGPT: your team, a client or everyone. No sign-up.
Claude, connected to your own Oracle EPM. Each person as themselves, every call checked and logged.
Related MCP Servers
- FlicenseAqualityDmaintenanceThe server facilitates natural language interactions for exploring and understanding codebases, providing insights into data models and system architecture using a cost-effective, simple setup with support for existing Claude Pro subscriptions.426-
- AlicenseNot gradedqualityFmaintenanceA modular server implementation for Claude AI assistants with integrated tools, enabling Claude to perform actions and access external resources like file systems, web searches, browser automation, financial data, and document generation.108MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that lets any LLM client query the Home Credit Default Risk SQLite database (307,511 loan applications) through 7 read-only tools, 4 resources, and 1 prompt over stdio, with natural language, SQL, and tool-calling interfaces.-
- FlicenseNot gradedqualityDmaintenanceMCP server that exposes the credit scoring model's deterministic tools (probability of default, SHAP explanations, typicality check, financial ratios) to AI agents, enabling natural language credit risk assessment.-