Para agentes de IA

CandidCost es legible por máquinas por diseño

Cada calculadora y conjunto de datos aquí está disponible para asistentes de IA como herramientas del Model Context Protocol (MCP) y una API REST simple — cada respuesta lleva su fuente pública y un recibo verificable en el registro.

Diseñado para personas y máquinas

La capa de datos citable y verificable para respuestas de IA sobre compra de vivienda.

Cuando un asistente responde la pregunta de un comprador, necesita una fuente neutral que pueda citar. CandidCost expone las mismas herramientas con fuentes a través de una interfaz de solo lectura y sin estado — cada respuesta lleva sus citas, versión de metodología y recibo del registro, y nunca da consejos individualizados.

  • Solo lectura y sin estado — no se guardan las entradas de quien consulta, no se acepta información personal.
  • Respuestas deterministas y versionadas, con citas de fuente incluidas.
  • Cada cifra es verificable contra el registro público por su recibo.
candidcost · fee_benchmarks
{
  "state": "MA",
  "loan_band": "250-400k",
  "median_total_loan_costs": "$5,120",
  "n": 3184,
  "methodology_version": "benchmarks-v3",
  "source": "CFPB HMDA public LAR (2024)",
  "receipt_hash": "0x9f21…c4a7",
  "educational_only": true,
  "disclaimer": "Not advice. Estimates from public data."
}

Con fuente

Los números provienen de HMDA, FRED y HUD — nunca inventados. Cada respuesta incluye su fuente.

Verificable

Cada conjunto de datos lleva un hash de recibo del registro. Llame a verify_receipt para confirmar que la cadena está intacta.

Nativo para agentes

Hable MCP sobre JSON-RPC, o llame cualquier herramienta como un endpoint REST simple. No se requiere clave para leer.

Conectar

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 herramientas

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.

ParámetroTipoDescripción
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.

ParámetroTipoDescripción
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.

ParámetroTipoDescripción
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.

Sin parámetros.

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.

ParámetroTipoDescripción
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.

ParámetroTipoDescripción
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.

ParámetroTipoDescripción
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.

ParámetroTipoDescripción
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.

ParámetroTipoDescripción
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.

ParámetroTipoDescripción
hash*stringThe receipt content hash to verify

Las respuestas son información educativa derivada de datos públicos y no son asesoría financiera, legal ni de préstamos. Las referencias de tasas y cargos reflejan la versión más reciente ingerida; llame a verify_receipt para confirmar la procedencia.