# HomeTaxChallenge for AI agents

HomeTaxChallenge helps homeowners check whether their property tax assessment is too high and build an appeal from comparable sales. Agents can use the same engine as https://www.hometaxchallenge.com.

Currently supported: Illinois (76 counties: Kane County, Winnebago County, Will County, DuPage County, Lake County, Kendall County, DeKalb County, Grundy County, McLean County, Kankakee County, Rock Island County, Logan County, Sangamon County, McHenry County, St. Clair County, Boone County, LaSalle County, Macon County, Vermilion County, Whiteside County, Ogle County, Knox County, Madison County, Champaign County, Peoria County, Tazewell County, Williamson County, Adams County, Jackson County, Henry County, Coles County, Macoupin County, Stephenson County, Woodford County, Franklin County, Marion County, Jefferson County, Livingston County, Effingham County, Lee County, Fulton County, Morgan County, Randolph County, Montgomery County, McDonough County, Iroquois County, Saline County, Jo Daviess County, Jersey County, Perry County, Douglas County, Crawford County, Hancock County, Piatt County, Bond County, Warren County, Carroll County, Mercer County, Clark County, Pike County, Washington County, White County, Ford County, Clay County, Mason County, Menard County, Cumberland County, Jasper County, Schuyler County, Brown County, Henderson County, Edwards County, Putnam County, Alexander County, Calhoun County, Pope County).

## Why use it
- Every supported county, from the official county assessment and sales records.
- Comparable sales, a suggested value range, estimated tax savings and the filing deadline where the county has published it, in one call.
- Lookups are free.

## MCP server
- URL: https://www.hometaxchallenge.com/mcp (streamable HTTP, stateless, JSON responses)
- JSON HTTP equivalent: GET https://www.hometaxchallenge.com/api/agent/list_counties; POST https://www.hometaxchallenge.com/api/agent/<tool> with a JSON body
- Optional header: X-Client-Name: <your agent or app name> (used for per-client limits)

## Use HTC from ChatGPT/Claude/Cursor
MCP endpoint: https://www.hometaxchallenge.com/mcp

**Claude (claude.ai / Desktop):** Customize → Connectors → Add → Custom → Web (older menus: Settings → Connectors → Add custom connector). Name: HomeTaxChallenge. Remote MCP server URL: https://www.hometaxchallenge.com/mcp. Authentication: No sign in.

Claude Desktop JSON config (`claude_desktop_config.json`), using the mcp-remote bridge:
```json
{
  "mcpServers": {
    "hometaxchallenge": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.hometaxchallenge.com/mcp"
      ]
    }
  }
}
```

**Cursor** (`~/.cursor/mcp.json` or the project's `.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "hometaxchallenge": {
      "url": "https://www.hometaxchallenge.com/mcp"
    }
  }
}
```

**ChatGPT:** On plans with developer mode: Settings → Apps → Advanced settings → turn on Developer mode, then Create app. Name: HomeTaxChallenge. MCP server URL: https://www.hometaxchallenge.com/mcp. Authentication: No authentication. Accept the warning and create it, then enable it in a chat from the + / Developer mode menu. (In the newer Plugins view: + → Add custom MCP server, same URL.)

Optional: send header `X-Client-Name: <your app>` on JSON calls.

## Tools
- list_counties: supported counties with tier, the 2026 appeal window/deadline status and filing method. Tier 1 counties: get_quote returns status quote_unavailable_yet with the lookup, a TBD deadline and the request_full_submission / email path (pass email on get_quote to store a lead); Tier 2+ return comps and savings.
- lookup_property {county, query}: find a property by address or parcel number (PIN).
- get_quote {county, pin, noticeValue?, noticeValueType?}: comparable sales, suggested value range, estimated savings and deadline.
- request_full_submission {county?, pin?, address?, email?, name?, notes?}: ask for a full appeal packet. Full submission packets are coming soon; email contact@hometaxchallenge.com to get one prepared now.

## Limits
- 10 calls/hour per IP (lookup, quote, full request).
- 50 calls/day per client (lookup, quote, full request).
- A global daily cap protects the service; over a limit you get a clear error (HTTP 429 on the JSON API).

## Pricing
- Lookups and quotes: free.
- Full appeal packet: coming soon (email contact@hometaxchallenge.com to get one prepared now).

## Disclaimer
HomeTaxChallenge is not a law firm and this is not legal advice. Estimates are informational. The property owner reviews and files the appeal with the county Board of Review.