Skip to content
PorchFacts

Agents & API

Docs

PorchFacts is a remote MCP server and a REST API. Add it to your assistant once, sign in, and ask in plain English; your assistant calls it when a question needs voucher rent, cash flow, or a four-way property analysis.

Connect

Connect in three steps: copy the server address, add it to your assistant, and sign in when it asks.

Server address

MCP server URL
https://porchfacts.com/mcp

The first time your assistant connects, it opens a PorchFacts sign-in page. Approve the request and the assistant can work on your behalf. To disconnect an assistant, remove the connector in that assistant's settings, or email support to end its access. API keys for the REST API are revoked on your account page.

The snippets below use section8yield as the connector id. It is stable on purpose: it comes from the product's former name, Section 8 Yield, and changing it would break setups that already use it.

Claude

  1. In Claude on the web or desktop, open Settings, then Connectors.
  2. Choose Add custom connector, name it PorchFacts, and paste the server address.
  3. Choose Connect and sign in to PorchFacts.

ChatGPT

  1. Open Settings, then Apps and Connectors, and turn on developer mode under Advanced settings.
  2. Choose Create, name it PorchFacts, paste the server address, and pick OAuth for authentication.
  3. Sign in when ChatGPT asks, then turn the connector on in a new chat.

Gemini

In Gemini CLI, add the server to ~/.gemini/settings.json:

Gemini CLI settings
{
  "mcpServers": {
    "section8yield": {
      "httpUrl": "https://porchfacts.com/mcp"
    }
  }
}

Then run /mcp auth section8yield inside Gemini CLI and sign in.

Muse

Add PorchFacts as a remote MCP connector with the server address above, then sign in when Muse asks.

Code editors

Claude Code

Claude Code command
claude mcp add --transport http section8yield https://porchfacts.com/mcp

Then run /mcp in Claude Code and choose Authenticate.

VS Code

Add to .vscode/mcp.json in your project:

VS Code MCP settings
{
  "servers": {
    "section8yield": {
      "type": "http",
      "url": "https://porchfacts.com/mcp"
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

Cursor MCP settings
{
  "mcpServers": {
    "section8yield": {
      "url": "https://porchfacts.com/mcp"
    }
  }
}

REST API

Every tool is also a REST endpoint, for GPT actions, Grok, other agents, and your own scripts. Calls count against your plan exactly as they do through MCP, and the answers are the same.

Quickstart

  1. Create an API key on your account page (Pro and Team plans).
  2. Send it as a bearer token. Replace s8y_your_key with your key:
Analyze one property with curl
curl -X POST https://porchfacts.com/api/v1/tools/analyze_property \
  -H "Authorization: Bearer s8y_your_key" \
  -H "Content-Type: application/json" \
  -d '{"listing": {"address": "3412 E 116th St, Cleveland, OH 44105", "price": 95000, "beds": 3, "baths": 1}, "goal": "cash_flow"}'

The answer is JSON with content (the same text your assistant sees), structuredContent, and isError. Errors are plain: 400 for input that does not match the tool, 401 for a missing or revoked key, 403 when your plan does not include API keys, and 429 when this month's analyses are used or a key sends more than 60 requests a minute.

ChatGPT GPT actions

  1. In the GPT editor, open Configure, then Create new action, and choose Import from URL: https://porchfacts.com/api/v1/openapi.json
  2. Under Authentication choose API Key, auth type Bearer, and paste your key.

Grok, other agents, and scripts

Give the agent the OpenAPI document, or call a tool directly: GET https://porchfacts.com/api/v1/tools lists every tool. A plain-text summary for agents is at /llms.txt.

Tools

Each tool works through MCP and as POST https://porchfacts.com/api/v1/tools/<name>. Your assistant picks the tool; you only need the names to call the REST API.

  • analyze_propertyAnalyze one property four ways
  • get_property_reportGet the property report
  • rank_homes_by_section8_cash_flowRank homes by Section 8 cash flow
  • search_homes_for_section8Search homes for sale for Section 8
  • get_section8_voucher_rentGet Section 8 voucher rent
  • compare_zip_codes_for_section8Compare ZIP codes for Section 8 rent
  • compare_section8_marketsCompare markets for Section 8 rentals
  • check_rent_reasonablenessCheck Section 8 rent reasonableness
  • model_section8_value_addModel a Section 8 value-add
  • create_section8_lender_reportCreate a Section 8 lender report
  • check_hoa_documentsCheck HOA documents for red flags
  • check_closing_documentsCompare a Loan Estimate with the Closing Disclosure
  • check_housing_authority_statusCheck housing authority status
  • section8_inspection_checklistSection 8 inspection checklist
  • save_section8_dealSave Section 8 deal
  • list_section8_dealsList saved Section 8 deals
  • delete_section8_dealDelete saved Section 8 deal
  • create_section8_buy_box_alertCreate Section 8 buy box alert
  • list_section8_alertsList Section 8 buy box alerts
  • delete_section8_alertDelete Section 8 buy box alert
  • report_section8_outcomeReport Section 8 lease outcome

Example prompts

  • What will a Section 8 voucher pay for a 3-bedroom house at 3412 E 116th St, Cleveland, OH 44105?
  • Rank single-family homes for sale under $150,000 in ZIP 44105 by monthly voucher cash flow with 20% down.
  • Which housing authority covers 77026, and is its payment standard Verified?
  • Compare voucher rent for 2-bedroom units in 44102, 44105, and 44108.
  • If the tenant pays electric heat instead of gas, how much does the rent to owner change for a 4-bedroom duplex unit in 44105?
  • Save this deal as "116th Street duplex" and alert me when a similar home under $130,000 is listed.

Reading the answers

Every number comes back marked Verified (read from the housing authority's own schedule) or Estimated (worked out from HUD data), with a source link and an effective date. Rent to owner is the payment standard minus the utility allowance for the utilities the tenant pays, before the authority's rent reasonableness check. Confirm with the housing authority before you buy.

How cash flow is worked out

For each home, rent is the voucher rent for every unit. Monthly cash flow is rent minus vacancy, minus operating costs (property tax, insurance, repairs, capital reserve, management, HOA, and any utilities the owner pays), minus the loan's principal and interest. Operating costs and vacancy before the loan give net operating income (NOI). PITI is principal, interest, taxes, and insurance. Cap rate is a year of NOI over the price. Cash on cash is a year of cash flow over the down payment plus closing costs. DSCR is NOI over principal and interest. Each monthly line is rounded to the cent; cap rate and cash on cash to 0.01%, DSCR to two decimals. Utilities the owner pays are priced from the same utility allowance schedule as the rent. These numbers are always Estimated.

Cash flow defaults

Any of these can be changed in your request. The interest rate defaults to this week's FRED 30-year fixed average (MORTGAGE30US).

  • 20% down: the usual minimum for an investor loan (80% loan to value on DSCR and conventional investment loans).
  • 30-year fixed, the term of the FRED MORTGAGE30US rate used as the default interest rate.
  • 3% of price in buyer closing costs, mid-range of the 2% to 5% typical for a financed purchase; counted as cash invested.
  • Property tax is each ZIP's effective rate from Census ACS 5-year estimates (median real estate taxes / median home value; the county's when the ZIP has no estimate). 1.5% of price a year only where ACS has neither. Override with the home's own tax bill.
  • Landlord insurance at 0.5% of price a year, with a $1,200 a year floor because low-priced homes still cost about $100 a month to insure.
  • 5% of rent: voucher tenants tend to stay longer than market tenants, but turnover adds inspection and HAP contract delays.
  • 8% of rent for repairs: voucher homes are often older and must pass annual inspections (NSPIRE).
  • 8% of rent set aside for capital items (roof, furnace, water heater) on older housing stock.
  • 10% of rent: a typical property manager fee; kept even when self-managing, to price your time.
  • Insurance in analyze_property and rankings is the midpoint of the NAIC state average homeowners premiums for homes insured near the price; the 0.5% rule applies only where no state average does.
  • HOA dues come from the listing; when a listing gives none, none are assumed.
  • The tenant pays every utility unless you say the owner pays some.

Four strategies for one property

The analyze_property tool works out four strategies for one home. Living in it: principal and interest, taxes, insurance, PMI while the down payment is under 20%, HOA, maintenance, and your utilities (shown as not included when you give none), plus the down payment and closing costs upfront. A traditional rental: your market rent, or the Census median gross rent for the ZIP and bedrooms (an area median that includes tenant-paid utilities, not a comp); NOI, cap rate, cash on cash, DSCR, and break-even occupancy (operating expenses plus principal and interest, over rent), and a downside case with rent 10% lower, vacancy 5 points higher, and expenses 10% higher. Section 8: the same cash flow as above. A fix and flip: ARV from the comps you give (lowest, median, highest, scaled by price per square foot when both square footages are known) or your ARV; rehab plus a contingency; buy closing, holding, and selling costs; the maximum offer by the 70% rule and after all costs and a target profit; and net profit in three scenarios, with a confidence grade. Every figure is marked with its tier: yours, area (a Census statistic), modeled, or verified (a published housing authority record).

Strategy defaults

  • Owner-occupied: 10% down, a common conventional down payment on a home you live in; under 20% down, the lender adds PMI.
  • Owner-occupied: PMI at 0.5% of the loan a year while the down payment is under 20%; quotes run from about 0.3% to 1.5% by credit score and loan to value.
  • Owner-occupied: maintenance at 1% of price a year, the usual rule of thumb for repairs and replacements.
  • Traditional rental: 20% down, the usual minimum for an investor loan (80% loan to value).
  • Traditional rental: 8% of rent for vacancy, about one month empty a year between tenants (1/12 is 8.3%).
  • Traditional rental: 5% of rent for repairs (no annual voucher inspection to pass).
  • Traditional rental: 5% of rent set aside for capital items (roof, furnace, water heater).
  • Traditional rental: 8% of rent for a property manager, the low end of the usual 8% to 10% fee.
  • Downside scenario: rent 10% lower.
  • Downside scenario: vacancy 5 points higher.
  • Downside scenario: operating expenses 10% higher than the base case's (costs do not fall when rent does).
  • Fix and flip: 10% down; flip lenders commonly lend up to 90% of the purchase price.
  • Fix and flip: 11% a year, interest only, the middle of the 10% to 12% commonly quoted for short-term flip loans (points not included).
  • Fix and flip: 6 months from purchase to sale, for rehab plus listing time.
  • Fix and flip, pessimistic: 3 more months of holding.
  • Fix and flip: $150 a month of utilities on the vacant home during rehab.
  • Fix and flip: selling costs at 8% of ARV (agent commissions, seller closing costs, and transfer taxes).
  • Fix and flip: a target profit of 10% of the base ARV for the all-costs maximum offer.
  • Fix and flip: 10% rehab contingency when the condition is known (inspected or scoped).
  • Fix and flip: 20% rehab contingency when the condition is unknown.
  • Fix and flip: the 70% rule, maximum offer = ARV x 70% - rehab.
  • Fix and flip: a comp sold more than 12 months ago is flagged as stale (still listed) and lowers confidence.

True monthly cost

The property report's true monthly cost is living in the home: principal and interest at this week's FRED 30-year fixed average (or your rate) with 10% down (or yours), PMI while the down payment is under 20%, property tax at the price under the state's rule, homeowners insurance at the midpoint of the NAIC state averages for homes insured near the price (or your quote), HOA dues you give, and the housing authority's utility allowance for the bedroom count as an Estimated stand-in for utility bills. The low and high totals add each line's low or high end: tax with and without the owner-occupant reduction, insurance at the lowest and highest state averages near the price. A line without its data is left out and named, never counted as $0. The same tax, insurance, loan payment and PMI are used by analyze_property. These numbers are always Estimated.

Payment shock and affordability

The payment a buyer faces in year one and year two, from the true monthly cost's own loan, PMI, tax and insurance lines. Year one escrows the seller's current tax bill from the county record, as lenders often do at first. Year two escrows the tax at the price; the escrow account then falls short by the year-one gap plus the larger cushion of up to two months that Regulation X allows (12 CFR 1024.17), and the servicer may spread that shortage over 12 months on top of the higher escrow. Insurance is held the same. With your gross monthly income, the year-two payment plus HOA over income is the front-end ratio, and adding your other debts gives the back-end ratio: comfortable within 31% and 36%, stretched within 40% and 43%, over beyond either, after the CFPB's guide, FHA's Handbook 4000.1 and Fannie Mae's Selling Guide. A lender decides the approval; these numbers are always Estimated.

Repairs ahead

The property report's repair reserve for the roof, the furnace and the water heater. Each part's age is the install year you give, else the year built from the property record, assumed original or of unknown age. Its expected life is InterNACHI's range for an asphalt shingle roof, a furnace and a conventional water heater. InterNACHI gives these as guidelines, not guarantees: life varies with use, weather, installation, maintenance and quality of materials. The monthly reserve is the replacement cost over the months of expected life left, at least 12, so a part at or past its expected life is budgeted to be replaced within a year; the low reserve pairs the low cost with the long life, the high one the high cost with the short life. Furnace and water heater prices are NREL's Residential Efficiency Measures Database (REMDB) installed cost range for a retrofit, one appliance each, without rebates or incentives, and not a quote for a project. No public roof price is used: REMDB has no roof replacement measure, and the Remodeling Cost vs. Value Report's terms forbid use in web applications without a license, so the roof has a reserve only from the roof cost you give. The bad case is the largest single replacement now. These numbers are always Estimated.

Honest investor numbers

The numbers a lender and a realist use, from the report's own itemized costs. Net operating income (NOI) is the rent less vacancy, management and repairs at the traditional rental defaults, the capital reserve from Repairs ahead (the midpoint of its combined reserve), tax at the price and insurance from the true monthly cost, and HOA you give. Cap rate is NOI times 12 over the price; cash on cash is the yearly cash flow after the loan over the down payment and closing costs; DSCR is NOI over principal and interest on an investor loan with 20% down at this week's FRED 30-year average or your rate. The largest loan is the one whose payment NOI covers 1.25 times. The 50% rule's NOI (half the rent) is shown beside ours. The bad case doubles vacancy and pays the largest single repair in year one; the reserves to hold are six months of the payment with tax, insurance and HOA or that year's shortfall, whichever is more. Loan rates are the 30-year average plus a stated spread you can change. Always Estimated, never a loan offer.

  • Debt service coverage of 1.25: Fannie Mae's minimum for conventional multifamily loans (5 or more units); lenders on 1 to 4 unit investor (DSCR) loans commonly ask for 1.20 to 1.25.
  • The 50% rule of thumb: operating expenses take half the rent, so NOI is half the rent.
  • 6 months of the payment with tax, insurance and HOA (PITIA): Fannie Mae's minimum reserves for an investment property purchase underwritten in DU.
  • Conventional investor loan: 0.75 point over the 30-year average, an assumption for Fannie Mae's investment-property price adjustment (charged on the loan, passed on as a higher rate).
  • DSCR loan: 1.5 points over the 30-year average, an assumption; these non-agency loans qualify on the rent, not your income, and price above agency loans.
  • HELOC: 1.5 points over the 30-year average, an assumption; HELOC rates float with the prime rate and are interest only while you draw.

Assumable loan

Taking over the seller's loan: its payment is worked out on the same amortization as every loan here, over the whole years left (from your number, or a 30-year loan from its origination year). The equity gap is the price minus the balance, all of it in cash without a second loan, or your down payment with the rest on a second loan at today's rate plus 2 points over the loan term. The blended payment is set against a new loan at today's rate with the same down payment. The value of the lower rate is the monthly saving discounted at today's rate over the holding period (7 years unless you give one) or the years left, whichever is shorter; it leaves out assumption fees and the balances owed when you sell. Principal and interest only, always Estimated, never a loan offer.

  • A second loan for the equity gap at today's 30-year rate plus 2 points: a second lien is repaid after the first, so lenders price it higher. Get a quote; this is not one.
  • The value of a low rate counts the monthly saving over 7 years of owning the home; give holding_years for your own plan.
  • From an origination year, the assumed loan is taken as a 30-year loan; give assumable_years_left when its term differs.

Section 8 owner rules

The rules owners trip on in the Housing Choice Voucher program, as the property report's Section 8 operations section cites them.

  • Rent increase notice: tell the housing authority at least 60 days before a new rent to owner takes effect (24 CFR 982.308(g)(4)). The new rent must still pass rent reasonableness (24 CFR 982.507). Your lease and state law set the notice the tenant gets.
  • Household changes: the housing authority approves who lives in the unit. The family must ask it before adding anyone and promptly report a birth, adoption or court-awarded custody; nobody else may live there except a foster child or live-in aide the authority approves (24 CFR 982.551(h)(2), (h)(4)). Send a new occupant to the authority, not just to your lease.
  • Changing who pays utilities: this changes the lease's utility terms, so assistance continues only after the authority approves a new tenancy and a new HAP contract is signed (24 CFR 982.308(g)(2)(i)). The HAP contract (HUD-52641) lists who pays each utility. Plan the change for the renewal.
  • Describing the unit: where state or local law protects source of income, refusing a voucher or writing "no Section 8" in an ad is unlawful. Describe the unit by its rent, size and the screening criteria you apply to every applicant; the report's Landlord rules gives the state and city law where covered.

Your numbers

Prices, HOA dues, and assumptions you give, and figures you save with a deal, are used as entered by you. They are marked Estimated and dated the day you gave them, because PorchFacts has not checked them.

Buy box alerts

A buy box saves what you are looking for: ZIP codes or a city, a top price, the fewest bedrooms, home types, the lowest monthly cash flow you accept, and your own cash flow assumptions. Once a day, each buy box with its alert on is searched through RentCast, ranked with your assumptions, and any new match is emailed to the address on your account. Each home is sent once per buy box. The price and cash flow in an alert are as of the day it matched and are Estimated.

Reported outcomes

Investors can report what happened after a voucher lease: the contract rent the housing authority approved, whether the home passed its first inspection, and the days it took to lease. Each report is checked by a person before it counts, never names a tenant, and is only shown combined with others: a figure appears once at least 3 approved reports for the same authority and bedroom count support it. These figures are Estimated, because they come from users, not from the authority.

Support

Email [email protected] with the prompt you used and what you expected. Security reports go to the security page.

Plans and limits are on the pricing page. Which authorities are Verified is on the coverage page.