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 com.candidcost/mcp and published from server.json in the repository. Discover every tool and its schema programmatically at GET /api/agent.

10 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.

ParameterTypeDescription
homePrice*numberHome price in US dollars
downPaymentPct*numberDown payment as a percent of price (0–100)
rateAnnualPct*numberAnnual interest rate percent, e.g. 6.5
termYears*integerLoan term in years (default 30)
statestringTwo-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.
countystring5-digit county FIPS code. When provided and its Census county rate is available, it takes priority over the state rate (more accurate).
propertyTaxRatePctnumberAnnual property tax rate, % of value. Overrides county/state-derived rates when supplied.
insuranceAnnual*numberAnnual homeowners insurance premium, US dollars
hoaMonthly*numberMonthly HOA dues, US dollars
maintenanceRatePct*numberAnnual maintenance reserve, % of home value (baseline before age adjustment)
pmiAnnualRatePct*numberAnnual PMI rate, % of loan, applied while LTV > 80%
homeYearBuiltintegerYear 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.

ParameterTypeDescription
grossMonthlyIncome*numberGross monthly income, US dollars
monthlyDebts*numberRecurring monthly debt payments (cards, autos, student loans), US dollars
downPayment*numberDown payment available, US dollars
rateAnnualPct*numberAnnual interest rate percent
termYears*integerLoan term in years (default 30)
propertyTaxRatePct*numberAnnual property tax rate, % of value
insuranceAnnual*numberAnnual homeowners insurance premium, US dollars
frontEndLimitPct*numberHousing DTI ceiling percent (default 28)
backEndLimitPct*numberTotal 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.

ParameterTypeDescription
state*stringTwo-letter US state code, e.g. "MA"
metricstringOne 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.

ParameterTypeDescription
statestringTwo-letter US state code to filter by
buyerstringBuyer 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.

ParameterTypeDescription
feestringFee 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.

ParameterTypeDescription
purchasePrice*numberPurchase price in US dollars
sellersCurrentAnnualTax*numberSeller's current annual property tax in US dollars (from the listing)
statestringTwo-letter US state code for the reassessment rate
countystring5-digit county FIPS; its Census effective rate takes priority over the state rate
reassessRatePctnumberEffective annual property-tax rate at reassessment, %. Overrides county/state.
insuranceAnnual*numberAnnual homeowners insurance, US dollars

pressure_check

Pressure Check — Walk-Away Math

Decompose the tradeoff a rushed buyer faces: the earnest money at risk by walking away versus what overpaying to "win" costs over the life of the loan. Given the earnest money at risk, the overpay amount over your walk-away price, down-payment percent, rate, and term, returns the cash and financed shares of the overpay, the extra monthly P&I, the lifetime cost of overpaying, and its ratio to the earnest money. Money is integer cents. Educational decomposition — it names the two numbers so they can be compared; it never tells the user to walk or stay.

ParameterTypeDescription
earnestMoney*numberEarnest money at risk if you walk away after removing contingencies, US dollars
overpay*numberHow much over your walk-away price the pressure would push you to pay, US dollars
downPaymentPct*numberDown payment as a percent of price (0–100); splits the overpay into cash-at-close vs. financed
rateAnnualPct*numberAnnual interest rate percent, e.g. 6.5
termYears*integerLoan term in years (default 30)

rent_vs_buy_estimate

Rent vs. Buy Net-Cost Estimate

Compare the net cost of owning against renting over a holding period and find the break-even year. Owning nets upfront cash and recurring carrying costs against sale proceeds (appreciated value − selling costs − remaining loan); renting nets rent paid against the investment gain on the cash a buyer would tie up. Dollar inputs are US dollars; money in the response is integer cents. Appreciation, rent growth, and investment return are user-set assumptions. Tax deductions are excluded (documented simplification). Educational decomposition — it reports both net costs and the break-even year; it never says rent or buy.

ParameterTypeDescription
homePrice*numberHome price in US dollars
monthlyRent*numberComparable monthly rent in US dollars
downPaymentPct*numberDown payment as a percent of price
rateAnnualPct*numberAnnual interest rate percent
termYears*integerLoan term in years
holdingYears*integerHow many years you plan to stay before selling
propertyTaxRatePct*numberAnnual property tax rate, % of value
insuranceAnnual*numberAnnual homeowners insurance, US dollars
maintenanceRatePct*numberAnnual maintenance reserve, % of home value
hoaMonthly*numberMonthly HOA dues, US dollars
closingCostPct*numberUpfront buy-side closing costs, % of price
sellingCostPct*numberSelling costs at exit, % of future value
annualAppreciationPct*numberAssumed annual home-price appreciation percent
annualRentIncreasePct*numberAssumed annual rent increase percent
investmentReturnPct*numberAssumed annual return a renter earns on invested cash percent

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.

ParameterTypeDescription
hash*stringThe 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.