For AI Agents

CandidCost is machine-readable by design

Every calculator and dataset here is available to AI assistants as Model Context Protocol (MCP) tools and a plain REST API — each answer carrying its public source and a verifiable ledger receipt.

Sourced

Numbers come from HMDA, FRED, and HUD — never invented. Each response includes its source.

Verifiable

Every dataset carries a ledger receipt hash. Call verify_receipt to confirm the chain is intact.

Agent-native

Speak MCP over JSON-RPC, or call any tool as a simple REST endpoint. No key required to read.

Connect

MCP endpoint (streamable HTTP, official SDK)

Point any MCP client at /api/mcp. Built on the official MCP SDK; every tool declares readOnlyHint and idempotentHint. Send Accept: application/json, text/event-stream. Public tier: 30 req/min (hard stop). Volume tier via Authorization: Bearer <key>.

POST /api/mcp

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "fee_benchmarks",
    "arguments": { "state": "MA", "metric": "total_loan_costs" }
  }
}

REST endpoint

Every tool is also a REST route. Use GET with query params or POST with a JSON body.

GET

/api/agent/true_cost_estimate
  ?homePrice=500000
  &downPaymentPct=10
  &rateAnnualPct=6.43

GET

/api/agent/verify_receipt?hash=a2c0…8b31

Add it to your AI

Point any MCP client at the endpoint above, or find CandidCost in the Model Context Protocol registry and one-click directories. The server is namespaced io.candidcost/mcp and published from server.json in the repository. Discover every tool and its schema programmatically at GET /api/agent.

8 tools

Discover these programmatically at GET /api/agent (JSON index) or via MCP tools/list.

true_cost_estimate

True Cost of Ownership Estimate

Estimate the full monthly cost of owning a home — principal & interest, property tax, insurance, PMI, HOA, and maintenance — and contrast it with the lender "approval" payment (PITI+PMI) to reveal the hidden monthly gap. Dollar inputs are US dollars; all money in the response is integer cents; rates are fixed-precision percent strings.

Parameter	Type	Description
homePrice*	number	Home price in US dollars
downPaymentPct*	number	Down payment as a percent of price (0–100)
rateAnnualPct*	number	Annual interest rate percent, e.g. 6.5
termYears*	integer	Loan term in years (default 30)
state	string	Two-letter US state code (e.g. "NJ"). When provided and propertyTaxRatePct is omitted, the Census ACS effective property-tax rate for that state is used.
county	string	5-digit county FIPS code. When provided and its Census county rate is available, it takes priority over the state rate (more accurate).
propertyTaxRatePct	number	Annual property tax rate, % of value. Overrides county/state-derived rates when supplied.
insuranceAnnual*	number	Annual homeowners insurance premium, US dollars
hoaMonthly*	number	Monthly HOA dues, US dollars
maintenanceRatePct*	number	Annual maintenance reserve, % of home value (baseline before age adjustment)
pmiAnnualRatePct*	number	Annual PMI rate, % of loan, applied while LTV > 80%
homeYearBuilt	integer	Year the home was built. Scales the maintenance reserve by age band: ×1.5 pre-1980, ×1.2 1980–2005, ×1.0 2006+.

affordability_estimate

Affordability / DTI Estimate

Compute front-end (housing) and back-end (total debt) DTI budgets from income and debts, and the home price implied by the binding limit. Reports the standard 28/36 thresholds without ever telling the user what they "can afford". Dollar inputs are US dollars; money in the response is integer cents.

Parameter	Type	Description
grossMonthlyIncome*	number	Gross monthly income, US dollars
monthlyDebts*	number	Recurring monthly debt payments (cards, autos, student loans), US dollars
downPayment*	number	Down payment available, US dollars
rateAnnualPct*	number	Annual interest rate percent
termYears*	integer	Loan term in years (default 30)
propertyTaxRatePct*	number	Annual property tax rate, % of value
insuranceAnnual*	number	Annual homeowners insurance premium, US dollars
frontEndLimitPct*	number	Housing DTI ceiling percent (default 28)
backEndLimitPct*	number	Total DTI ceiling percent (default 36)

fee_benchmarks

HMDA Fee & Rate-Spread Benchmarks

Return closing-cost and rate-spread percentile distributions (p25/p50/p75 + mean) for a US state, computed from the row-level CFPB HMDA LAR for originated, first-lien, home-purchase loans. Cells with fewer than 25 records are suppressed. Dollar metrics are integer cents (…Cents); percent metrics are fixed-precision strings (…Pct). Each distribution carries a ledger receipt hash for verification.

Parameter	Type	Description
state*	string	Two-letter US state code, e.g. "MA"
metric	string	One of: total_loan_costs, origination_charges, rate_spread, interest_rate. Omit to return all metrics.

benchmark_rates

Current Benchmark Mortgage Rates

Return the latest benchmark mortgage rates (e.g. 30-year and 15-year fixed) from the Federal Reserve (FRED), each with its observation date and ledger receipt. Rates are fixed-precision percent strings.

No parameters.

search_dpa_programs

Search Down Payment Assistance Programs

Find down payment assistance (DPA) programs by US state and/or buyer type. Includes national programs. Each result links to its official government source and carries a ledger receipt and last-verified date.

Parameter	Type	Description
state	string	Two-letter US state code to filter by
buyer	string	Buyer type filter, e.g. "first-time", "veteran", "rural", "teacher"

decode_loan_estimate_fee

Decode a Loan Estimate Fee

Classify a mortgage Loan Estimate fee by CFPB section and control class (set by lender, shoppable, third-party, government, or prepaid), with a plain-language explanation and an educational question a buyer could ask. Omit "fee" to list the full catalog.

Parameter	Type	Description
fee	string	Fee name or keyword, e.g. "origination", "title"

payment_shock_estimate

Year-2 Property-Tax Payment-Shock Estimate

Estimate why a mortgage payment often jumps in year two: escrow at closing is sized from the seller's current tax bill, but the county reassesses at your purchase price, and RESPA spreads the resulting escrow shortage over 12 months. Given the purchase price, the seller's current annual tax (from the listing), a state (or county FIPS) for the reassessment rate, and insurance, returns the year-1 escrow, the year-2 ongoing escrow, the temporary catch-up peak, and the jump. Money is integer cents. This decomposes the mechanics; it is not a prediction of your specific bill.

Parameter	Type	Description
purchasePrice*	number	Purchase price in US dollars
sellersCurrentAnnualTax*	number	Seller's current annual property tax in US dollars (from the listing)
state	string	Two-letter US state code for the reassessment rate
county	string	5-digit county FIPS; its Census effective rate takes priority over the state rate
reassessRatePct	number	Effective annual property-tax rate at reassessment, %. Overrides county/state.
insuranceAnnual*	number	Annual homeowners insurance, US dollars

verify_receipt

Verify a Data Receipt

Verify a CandidCost ledger receipt hash (full sha256 or short "3f9a…c21e" form). Confirms the receipt exists and that its dataset hash chain is intact, proving the underlying data has not been altered since ingestion.

Parameter	Type	Description
hash*	string	The receipt content hash to verify

Responses are educational information derived from public data and are not financial, legal, or lending advice. Rate and fee benchmarks reflect the most recent ingested vintage; call verify_receipt to confirm provenance.