title: Creddy emoji: 📊 colorFrom: indigo colorTo: blue sdk: docker app_port: 7860 pinned: false

Creddy

A credit-risk analytics MCP server for Claude & ChatGPT. Ask questions in plain language → it writes safe, read-only SQL over 30,000 real labeled credit records, scores default risk with an interpretable model, and pulls live data from Turkey's Central Bank (TCMB) — all over the Model Context Protocol.

⚠️ Disclaimer: This is an educational / portfolio project. The labeled data is the public UCI "Default of Credit Card Clients" dataset (Taiwan, 2005). It is not a real lending system and must not be used for actual credit decisions.

Related MCP server: nl2sql-mcp

💬 Example questions

Ask your assistant:

• "What's the default rate by education level?" → run_query

• "24 years old, credit limit 20k, 2-month delay in September — will this client default?" → predict_default

• "How good is the risk model (AUC, recall)?" → model_metrics

• "Do clients with higher credit limits default less?" → run_query

• "What are the current USD, EUR and gold prices?" → tcmb_indicators (live TCMB)

• "Find TCMB series about credit-card spending." → tcmb_search (live TCMB)

• "Which columns are in the data?" → describe_schema

Answers come from real, labeled data and an actually trained model — not guesses.

👥 Who is it for?

🧰 Tools (9)

🚀 Connect it (no install)

The server is live (Hugging Face Spaces) — most people need zero setup. Pick your client:

ChatGPT

1. ChatGPT → Settings → Connectors → Advanced → Developer mode (enable).

2. Add connector and enter the MCP URL:

   https://onatozmenn-creddy-mcp.hf.space/mcp

3. Save. Now ask "What's the default rate by education level?" in chat.

Custom MCP tools only appear on accounts with Developer mode enabled.

Claude Desktop

Add to claude_desktop_config.json (Windows: %APPDATA%\Claude\claude_desktop_config.json · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "creddy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://onatozmenn-creddy-mcp.hf.space/mcp"]
    }
  }
}

Restart Claude Desktop; the tools show up in the 🔨 menu. (Requires Node.js for npx.)

Claude.ai (web)

On Pro / Max / Team (and Free — one connector) you can connect a remote MCP directly:

1. Settings → Connectors → Add custom connector.

2. Enter the MCP URL (leave OAuth fields empty — the server needs no auth):

   https://onatozmenn-creddy-mcp.hf.space/mcp

3. Add, then enable Creddy from the "+" → Connectors menu in a chat.

Smithery (one command)

npx -y @smithery/cli install onatozmen44/creddy-mcp --client claude

VS Code / Cursor

VS Code — .vscode/mcp.json:

{ "servers": { "creddy": { "type": "http", "url": "https://onatozmenn-creddy-mcp.hf.space/mcp" } } }

Cursor — .cursor/mcp.json (note the mcpServers key):

{ "mcpServers": { "creddy": { "url": "https://onatozmenn-creddy-mcp.hf.space/mcp" } } }

Architecture

flowchart LR
    User([User]) -- "natural language" --> Client["Claude / ChatGPT / IDE"]
    Client -- "MCP (stdio or HTTP)" --> Server["Creddy MCP server (FastMCP)"]
    Server -- "run_query" --> Guard["SQL guard (sqlglot)"]
    Guard --> DB[("Postgres (read-only)\nreal credit_clients")]
    Server -- "predict_default / model_metrics" --> Model[["Risk model (scikit-learn)"]]
    Server -- "tcmb_indicators / tcmb_search / tcmb_series" --> EVDS[["TCMB EVDS (live)"]]
    DB --> Server
    Model --> Server
    EVDS --> Server
    Server -- "results" --> Client --> User

Two independent safety layers protect the database: the SQL guard (sqlglot — SELECT-only, single statement, row cap) and a read-only DB session. Model-generated SQL is never trusted blindly.

Real data sources

Risk model

creddy train-model trains an interpretable logistic-regression pipeline (standardize numerics + one-hot encode categoricals) on the real data with an 80/20 split. It reports AUC, accuracy, precision, recall, F1, KS, picks the decision threshold with Youden's J, and saves the model. Every predict_default returns the probability, a risk band, and the signed top factors behind that specific decision — explainable, adverse-action friendly.

Current hold-out performance: AUC ≈ 0.71, KS ≈ 0.37. A low-risk profile scores ~12% and a high-risk profile ~58% (base rate ≈ 22%) — meaningful scores, not just rankings.

🛠️ Run locally

Prerequisites: Python 3.10+ and Docker.

docker compose up -d                 # local Postgres
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
Copy-Item .env.example .env
creddy setup                         # schema + real data + trained model
creddy serve                         # stdio  (or: creddy serve --http)
python eval/run_eval.py ; pytest     # 12/12 eval, 24 tests

CLI

creddy init-db | load-data [--limit N] | train-model | setup | serve [--http --host H --port P]

☁️ Self-host for free (Hugging Face + Neon)

1. Managed Postgres: create a free serverless DB on Neon or Supabase; note host / db / user / password.

2. Hugging Face Space: create a Docker Space and push this repo (it ships a Dockerfile + docker-entrypoint.sh). Add the DB as Space secrets:

   CREDDY_DB_HOST, CREDDY_DB_PORT, CREDDY_DB_NAME, CREDDY_DB_USER, CREDDY_DB_PASSWORD
   CREDDY_DB_SSLMODE=require        # Neon / Supabase require SSL
   CREDDY_TCMB_API_KEY             # optional

   On first boot the container bootstraps (schema + data + model) and serves at https://<user>-<space>.hf.space/mcp.

3. Keep it awake (optional): a GitHub Actions workflow (.github/workflows/keepalive.yml) pings the server every 30 minutes — set a repo secret MCP_URL to your /mcp URL.

Data model (credit_clients)

Monetary columns are in NT$; pay_* are repayment-status codes per month (-1/0 = paid duly, >=1 = months of delay); defaulted is the label.

client_id, credit_limit, sex, education, marriage, age,
pay_sep..pay_apr,          -- repayment status (6 months)
bill_sep..bill_apr,        -- bill statement amounts
pay_amt_sep..pay_amt_apr,  -- amounts paid
defaulted                  -- TRUE = defaulted next month

Project layout

sql/schema.sql              # Postgres DDL
src/creddy/
  config.py  db.py  sql_guard.py
  data_loader.py            # loads the real UCI dataset (ucimlrepo)
  risk_model.py             # trains + serves the default-risk model (scikit-learn)
  tcmb.py                   # live TCMB EVDS client
  server.py  cli.py
eval/                       # golden SQL + evaluation harness
tests/                      # unit tests (no DB / no network required)
Dockerfile, docker-entrypoint.sh   # container image for hosting

Design decisions

• Real, labeled data over synthetic — labels come from the source, so the risk story is genuine.

• Interpretable model on purpose — signed per-decision factors (explainable scoring) over a marginally higher AUC.

• Guard before LLM trust — AST inspection blocks DML/DDL, statement stacking and COPY/SET; the DB session is independently read-only.

• Eval as a first-class artifact — eval/ turns "does the SQL layer work?" into a measurable, CI-friendly pass rate.

Security

• Read-only SELECT only, enforced at two layers (parser + DB session); per-query row cap.

• Secrets (DB password, TCMB key) come from the environment, never hard-coded.

• The UCI data is public and anonymized — no real PII.

Honest note on tcmb_series

TCMB is migrating EVDS2 → EVDS3. The live tcmb_indicators and key-authenticated tcmb_search tools work today; the documented key-based public REST service that tcmb_series targets is currently offline behind that migration. Set CREDDY_TCMB_BASE_URL to the current endpoint once it is republished.

License

MIT