# loan-risk-mcp
demo project only. no production credit risk logic

# Loan & Risk Assessment MCP Server

A small Model Context Protocol (MCP) server built for a **Digital Banking
Assistant** Copilot Studio agent. It exposes three tools the agent can call
when it needs real computation instead of guessing:

| Tool | Purpose |
|---|---|
| `calculate_dti` | Debt-to-Income ratio + eligibility band |
| `amortization_schedule` | Monthly payment + total interest for a loan |
| `flag_risk_factors` | Explainable, rules-based risk score with reasons |

> **Disclaimer:** This is a portfolio/demo project. The risk logic is a
> transparent toy rule set, not a real credit model. Any production use
> would require fair-lending, compliance, and model-risk review.

## Architecture

```
User ── chats with ──▶ Copilot Studio Agent ("Digital Banking Assistant")
                              │
                              │  calls tool over MCP (Streamable HTTP)
                              ▼
                    Loan & Risk Assessment MCP Server (this repo)
                              │
                              ▼
                 Plain-language result returned into the conversation
```

The MCP server is a *tool* the agent reaches for mid-conversation — it's
part of the same Digital Banking Assistant project, not a separate demo.

## Project structure

```
loan-risk-mcp/
├── server.py         # The MCP server + 3 tools
├── test_tools.py      # Direct unit tests of the tool logic
├── requirements.txt    # Pinned dependency versions
└── README.md
```

## Setup

```bash
python3 -m venv venv
source venv/bin/activate        # venv\Scripts\activate on Windows
pip install -r requirements.txt
```

## Testing the logic

Run the tool functions directly (no MCP transport involved) to confirm the
math is right before wiring anything up:

```bash
python test_tools.py
```

## Running the server

**Local / stdio** (for local MCP clients, e.g. Claude Desktop, MCP Inspector):

```bash
python server.py
```

**HTTP** (required for a cloud client like Copilot Studio to reach it):

```bash
python server.py --http --port 8000
```

You can sanity-check the HTTP server with the official MCP Inspector:

```bash
npx @modelcontextprotocol/inspector
# then point it at http://localhost:8000/mcp
```

## Example call and response

Request: `calculate_dti(monthly_income=5000, monthly_debts=1000)`

```json
{
  "dti_ratio_percent": 20.0,
  "band": "good",
  "explanation": "DTI of 20.0% is at or below the common 35% affordability threshold. Generally considered healthy."
}
```

## Notes

- This demonstrates pro-code (Python MCP server) + low-code (Copilot
  Studio topics) working together — the direction the platform is
  actively moving toward with connected agents and MCP.
- The risk tool is deliberately rules-based and explainable rather than a
  black-box ML score, which mirrors how banks actually need AI outputs to
  be auditable.
- Call out clearly in interviews that this is a demo: real underwriting
  logic requires far more rigor, data, and compliance sign-off.