Underwriting MCP Server

A headless Model Context Protocol connector that lets you underwrite commercial and multifamily deals inside a Claude chat. Claude runs the conversation; this server does the arithmetic that must be exact (NOI, valuation, debt sizing, DSCR, returns) and serves your firm's underwriting methodology so every conversation underwrites the same way.

There is no web UI. The interface is Claude with this connector attached.

This server does deterministic math + methodology only. It does not open, fill, or recalculate Commercial_Template.xlsx — that's the Skills pipeline's job in code-execution. The two share the same underwriting constants so they never disagree.

Stack

• Next.js (App Router) + mcp-handler — wraps the route as an MCP endpoint over stateless Streamable HTTP (no SSE, no Redis; free-tier friendly).
• TypeScript + Zod for tool input contracts.
• Deploy target: Vercel (Hobby/free tier).

What it exposes

Tools (lib/calc/)

Group	Tools
Common (§4.1)	calculate_noi, value_from_cap_rate, implied_cap_rate, size_debt, debt_metrics, cash_on_cash, equity_required, exit_value, run_scenarios, deal_summary
Commercial (§4.2)	summarize_rent_roll, market_rent_gap, nnn_reimbursement, rollover_exposure
Multifamily (§4.3)	summarize_unit_mix, economic_occupancy, per_unit_metrics, proforma_rent_growth, mf_expense_defaults

Resources (lib/methodology/)

underwriting-conventions, scenario-definitions, commercial-field-map, multifamily-field-map, template-version — served over underwriting://… URIs.

Prompts (lib/prompts/)

underwrite_retail_commercial, underwrite_multifamily — guided openers that collect the right inputs, call the tools in order, and present the four-scenario grid.

Conventions (enforced)

• Four scenarios always: List / Target / Probable / Conservative. Per-scenario levers are cap rate, LTV, exit cap rate; everything else is shared.
• Rates are fractions — 0.055 = 5.5%. The server rejects rate-like inputs > 1.0 to catch the classic 5-vs-0.05 bug.
• Stabilization year selector (2/3/4, default 4); any stabilized result states which year it used.
• Every denominator (cap rate, equity, loan, GPR) is guarded — clear error instead of Infinity/NaN.
• Multifamily defaults (overridable): mgmt fee 3% of EGI, replacement reserves $250/unit/yr, rent trend 3%/yr.

Develop

npm install
npm test          # hand-checked deal per asset class (node:test via tsx)
npm run typecheck # tsc --noEmit
npm run dev       # http://localhost:3000/api/mcp

Deploy (free tier)

1. npm test — confirm every formula matches its hand-checked deal.
2. Push to GitHub.
3. Vercel → New Project → import repo → Deploy (Node auto-detected).
4. Your endpoint is https://<project>.vercel.app/api/mcp.
5. (Optional) set MCP_API_KEY in Vercel env to require Authorization: Bearer <key>.

Add the connector in Claude

Requires a Pro, Max, Team, or Enterprise plan (custom connectors over remote MCP).

1. Settings → Connectors → Add custom connector.
2. Paste the …/api/mcp URL; complete auth if you set a key.
3. Start a chat, confirm the tools/prompts appear, run the two walkthroughs.

Layout

app/api/mcp/route.ts   # mcp-handler entry: registers tools, resources, prompts + shared-key auth
lib/calc/finance.ts    # §5 primitives (debt, DSCR, value, exit)
lib/calc/common.ts     # §4.1 common tools incl. run_scenarios
lib/calc/commercial.ts # §4.2 retail/office/net-lease
lib/calc/multifamily.ts# §4.3 multifamily
lib/validate.ts        # fraction-vs-percent + zero-denominator guards
lib/methodology/       # §6 resources (source of truth, one file each)
lib/prompts/           # §7 guided flows
test/                  # one hand-checked deal per asset class

Roadmap

• Phase 4 — hardening: OAuth via withMcpAuth, rate limiting, multi-year levered cash flow / IRR (ARGUS-style) if desired.