UK Mortgage Repayment MCP

Tool-only MCP server for estimating UK repayment mortgage payments in ChatGPT.

Build and run locally (no ngrok)

You can develop and test both the MCP server and browser front end entirely on your machine. No public URL or tunnel is needed.

Prerequisites

• Node.js 22 or later (node --version)

• npm

Install the root dependencies once:

npm install

Install the front-end dependencies once:

cd test-client
npm install
cd ..

1. Start the MCP server

In the repository root, run:

npm run dev

The server listens at:

http://localhost:8787/mcp

Use PORT=9000 npm run dev to choose a different port.

Leave this terminal running.

2. Start the local front end and chat API

Open a second terminal in the repository root and run:

cd test-client
npm run dev

This starts the browser UI on port 5173 and the local chat-orchestrator API on port 5174. The browser and orchestrator are local; generating chat replies uses OpenRouter and needs your API key and internet access.

Before starting it, create test-client/.env if it does not already exist:

OPENROUTER_API_KEY=your_api_key

The protected local UI also needs hashed login credentials. Generate them without writing the password itself to .env:

read -s CHAT_H_LOCAL_PASSWORD
CHAT_H_PASSWORD="$CHAT_H_LOCAL_PASSWORD" node scripts/create-auth-values.mjs >> test-client/.env
unset CHAT_H_LOCAL_PASSWORD

The generated username defaults to hsbc. Sign in with that username and the password entered at the prompt.

Open http://127.0.0.1:5173/. The default MCP endpoint is http://127.0.0.1:8787/mcp. You can use both the chat composer and the MCP Connect control.

Direct MCP controls only (no chat)

If you specifically want to test only MCP JSON-RPC calls and do not need the chat composer or an OpenRouter key, run this instead:

cd test-client
npm run dev:ui

Use the MCP Connect control in this mode to inspect the available server tools. The chat composer requires the local port-5174 API and will fail if used with dev:ui. See the test-client README for model and endpoint settings.

Related MCP server: Real Estate MCP Server

Tools

calculate_mortgage_repayment

Inputs:

• loanAmount: mortgage loan amount in pounds sterling

• annualInterestRatePercent: nominal annual interest rate, for example 5.25

• termYears: whole mortgage term in years

• monthlyOverpayment: optional extra monthly repayment in pounds sterling

Outputs include monthly payment, total paid, total interest, and overpayment impact when provided.

find_mortgage_product_rates

Inputs:

• propertyValue: property value in pounds sterling

• loanAmount: borrowing amount in pounds sterling

• termYears: mortgage term from 2 to 40 whole years

• depositAmount: optional; if supplied, it must equal property value minus borrowing

It generates illustrative 2/3/5-year fixed and 2-year tracker products from the calculated LTV band. Each result includes the initial rate, monthly repayment, product fee, estimated APRC, reversion rate, and maximum LTV. These are deterministic demo calculations, not live rates, availability, eligibility, or offers.

mortgageNeed is optional and defaults to switch_residential. The supported values are switch_residential, first_time_buyer, move_home, remortgage, buy_to_let, remortgage_buy_to_let, and switch_buy_to_let. It records the selected customer journey; every journey uses the same deterministic illustrative pricing algorithm.

get_customer_support

Inputs:

• topic: general (default) or mortgage

Outputs include official-source-linked HSBC UK contact options and phone numbers. The values are a local snapshot for the test tool; use the returned official contact page as the source of truth for current details and opening hours. General support output also includes HSBC's contact/chat guidance and online-banking links.

Using ChatGPT developer mode

ChatGPT's hosted service cannot reach 127.0.0.1 or localhost on your computer. Therefore, without a public HTTPS endpoint, use the local browser client or MCP Inspector to develop and test the server. Connecting the MCP directly to ChatGPT developer mode requires a publicly reachable HTTPS URL; this repository does not require ngrok for local development.

Verify

npm test
npm run build
npm run typecheck

You can also test the MCP endpoint with the MCP Inspector:

npx @modelcontextprotocol/inspector@latest --server-url http://localhost:8787/mcp --transport http

The calculation is an estimate for illustration only and is not financial advice.

Private production deployment

The production deployment is isolated from the other applications on the existing VM:

• UI: https://chat-h-prod-ks-2026.web.app

• protected API and MCP: https://chat-h.35.211.52.83.nip.io

• loopback services: chat-h-mcp on 127.0.0.1:8787 and chat-h-web on 127.0.0.1:5174

• releases: /opt/chat-h/releases/<release-id> with /opt/chat-h/current

• secrets: /etc/chat-h/app.env, root-owned with mode 0600

The public Firebase files contain only the login shell and application code. The password is verified by the VM using a salted scrypt hash. A successful login stores a signed 12-hour bearer token in the current tab's sessionStorage; the password is never persisted. /health, /chat, and /mcp all require that token.

First deployment

The exact Firebase project must exist and be visible in firebase projects:list. Create only this project ID; if it is unavailable, stop rather than substituting another ID:

firebase projects:create chat-h-prod-ks-2026 --display-name "Chat-H Prod"

Record the existing applications' baseline, then deploy:

./scripts/preflight-existing.sh

export OPENROUTER_API_KEY='...'
export CHAT_H_USERNAME='hsbc'
export CHAT_H_PASSWORD='...'
./scripts/deploy-prod.sh

The deploy script runs all 14 MCP tests, typechecking, both builds, client checks, and the authentication integration check. It then uploads a versioned release, creates the dedicated system user and services, obtains the isolated Let’s Encrypt certificate if needed, validates Nginx before reload, deploys Firebase with the explicit --project chat-h-prod-ks-2026 argument, and runs the production smoke suite. It does not address another Firebase project or restart an existing application service.

Run the smoke suite again at any time:

CHAT_H_USERNAME='hsbc' CHAT_H_PASSWORD='...' ./scripts/smoke-prod.sh

After deployment, repeat ./scripts/preflight-existing.sh and compare its service/listener output with the recorded baseline.

Rollback

To switch only the VM services back to the previously deployed Chat-H release:

./scripts/rollback-prod.sh

Firebase Hosting has an independent release history. If its UI also needs to be reverted, use the rollback action for the chat-h-prod-ks-2026 site in the Firebase Hosting console. Do not roll back or redeploy WealthTrack, Pension Dashboard, or Stock Picker.

To disable Chat-H without touching another app:

gcloud compute ssh clawdbot-vm \
  --project clawdbot-ks-2026 --zone us-east1-b \
  --command 'sudo systemctl disable --now chat-h-mcp chat-h-web'