Risk Assessment MCP Server

A mortgage risk underwriting server built on FastMCP 3.x that exposes individual risk calculation tools and an aggregation tool for producing loan recommendations. Built from the FastMCP server template.

Tools

calculate_dti

Computes the Debt-to-Income ratio as a percentage. Rates Low below 36%, Medium at 36--43%, High above 43%.

Parameters: monthly_income (float), monthly_debts (float)

Returns: JSON with metric, value, rating, guidance.

{"monthly_income": 8000, "monthly_debts": 2400}

calculate_ltv

Computes the Loan-to-Value ratio as a percentage. Rates Low below 60%, Medium at 60--80%, High above 80%. Includes pmi_required flag.

Parameters: loan_amount (float), property_value (float)

Returns: JSON with metric, value, rating, guidance, pmi_required.

{"loan_amount": 320000, "property_value": 400000}

evaluate_credit_risk

Evaluates credit risk from a FICO-range score (300--850). Rates Low above 680, Medium at 620--680, High below 620.

Parameters: credit_score (int), source (str, default "self_reported")

Returns: JSON with metric, value, rating, guidance, source.

{"credit_score": 720, "source": "experian"}

assess_income_stability

Takes a list of employment statuses for all borrowers and returns the worst-case rating. Valid statuses: w2_employee, self_employed, retired, unemployed, other.

Parameters: employment_statuses (list of strings)

Returns: JSON with metric, statuses, rating, guidance, individual_ratings.

{"employment_statuses": ["w2_employee", "self_employed"]}

assess_asset_sufficiency

Checks asset reserves as a percentage of the loan amount. Rates Low above 20%, Medium at 10--20%, High below 10%.

Parameters: total_assets (float), loan_amount (float)

Returns: JSON with metric, value, rating, guidance.

{"total_assets": 90000, "loan_amount": 350000}

generate_risk_recommendation

Aggregates all five risk assessments plus document status and optional ML predictions into a final underwriting decision. The decision logic applies deny triggers (DTI > 55%, credit < 580, LTV > 97%, all borrowers unemployed), suspend triggers (missing documents), and conditional triggers (PMI, elevated DTI, self-employment documentation). Compensating factors such as strong credit offsetting high DTI are also considered.

Parameters: dti_value, dti_rating, ltv_value, ltv_rating, credit_score, credit_rating, income_rating, asset_rating, employment_statuses, has_financial_docs, has_credit_report, document_count, ml_prediction (optional), ml_confidence (optional)

Returns: JSON with recommendation, rationale, conditions, compensating_factors, overall_risk, warnings, risk_summary.

{
  "dti_value": 38.5, "dti_rating": "Medium",
  "ltv_value": 75.0, "ltv_rating": "Medium",
  "credit_score": 720, "credit_rating": "Low",
  "income_rating": "Low", "asset_rating": "Low",
  "employment_statuses": ["w2_employee"],
  "has_financial_docs": true,
  "has_credit_report": true,
  "document_count": 5
}

Quick Start

Local Development

make install
make run-local

# In another terminal, test with cmcp
cmcp ".venv/bin/python -m src.main" tools/list
cmcp ".venv/bin/python -m src.main" tools/call calculate_dti '{"monthly_income": 8000, "monthly_debts": 2400}'

Deploy to OpenShift

make deploy PROJECT=mcp-risk-server

The server is deployed at: https://mcp-server-mcp-risk-server.apps.cluster-z9hbt.z9hbt.sandbox1495.opentlc.com/mcp/

Testing

# Run all 53 tests
make test

# Run a single test file
.venv/bin/pytest tests/test_risk_calculations.py -v

# Test against local STDIO server with cmcp
make test-local

Architecture

The server uses FastMCP 3.x with FileSystemProvider for automatic tool discovery. Tools use standalone @tool decorators (no shared server instance). The server runs in STDIO mode locally and uses streamable-http transport on port 8080 when deployed to OpenShift.

Tool source lives in two files under src/tools/: risk_calculations.py (five calculation tools) and risk_recommendation.py (the aggregation tool). The recommendation logic is factored into a pure compute_recommendation() function for direct use in tests.

Environment Variables

License

This project is licensed under the MIT License. See the LICENSE file for details.