MCP Agent Workflows

PadStats provides an MCP server, padstats-mcp, that lets AI agents call the Intelligence API as structured tools instead of scraping pages, guessing request payloads, or asking you to assemble API calls manually.

The MCP server is a protocol adapter over the public PadStats API. It uses your existing API key, sends requests to the normal /v1 endpoints, and returns the standard {data, meta, error} response shape.

Credits

Agent clients can call tools multiple times in one conversation. Successful calls use the normal PadStats credit system. Monitor meta.credits in tool responses and keep tool caps conservative.

How it works

Claude, Cursor, or another MCP client
  -> starts or connects to padstats-mcp
  -> lists available PadStats tools
  -> calls the right tool with JSON arguments
  -> receives structured PadStats API results

padstats-mcp does not bypass authentication, billing, rate limits, or API validation. Each tool call goes through the same API path as a direct HTTP request with X-API-Key.

Prerequisites

• Python 3.11 or newer.
• An existing PadStats API key.
• An MCP-compatible client such as Claude Desktop, Cursor, Codex, or another local stdio MCP client.
• A conservative testing cap, such as 3 comparables and 50 crime records, while you are validating agent behavior.

Install

Install the package into the Python environment your MCP client will launch:

python -m pip install --upgrade padstats-mcp
python -m padstats_mcp --help

The console script is:

padstats-mcp

For desktop MCP clients, the most reliable launch form is:

python -m padstats_mcp

That form avoids PATH issues and makes it easier to use the exact Python environment where padstats-mcp is installed.

During a private alpha, PadStats may provide a private package URL instead of public PyPI installation. The runtime configuration below is the same either way.

Environment variables

Variable	Required	Default	Description
PADSTATS_API_KEY	Yes	-	Your existing PadStats API key. Sent as X-API-Key.
PADSTATS_API_BASE_URL	No	https://api.padstats.io	API environment to call.
PADSTATS_MCP_TRANSPORT	No	stdio	stdio or streamable-http.
PADSTATS_MCP_MAX_NUM_COMPS	No	5	Maximum comparables an agent can request.
PADSTATS_MCP_MAX_CRIME_LIMIT	No	100	Maximum crime incidents/details an agent can request.
PADSTATS_MCP_MAX_CRIME_RADIUS_MI	No	2.0	Maximum crime search radius.
PADSTATS_MCP_MAX_RENTAL_UNITS	No	10	Maximum rental units in one MCP request.
PADSTATS_MCP_MAX_CENSUS_KEYS	No	10	Maximum census variables in one MCP request.

Claude Desktop setup

Add a PadStats MCP server entry to your Claude Desktop MCP config:

{
  "mcpServers": {
    "padstats": {
      "command": "python",
      "args": ["-m", "padstats_mcp"],
      "env": {
        "PADSTATS_API_KEY": "YOUR_API_KEY",
        "PADSTATS_API_BASE_URL": "https://api.padstats.io",
        "PADSTATS_MCP_MAX_NUM_COMPS": "3",
        "PADSTATS_MCP_MAX_CRIME_LIMIT": "50"
      }
    }
  }
}

If your config already contains other top-level keys such as preferences, merge mcpServers into the same JSON object. Do not create a second JSON object in the file.

On Windows, if Claude launches a different Python than the one where the package is installed, use the full Python path:

"command": "C:\\Python313\\python.exe"

Restart Claude Desktop after changing the config. The PadStats tools should appear in Claude's available MCP tools.

Cursor setup

Use the same stdio command and environment shape in Cursor's MCP configuration:

{
  "mcpServers": {
    "padstats": {
      "command": "python",
      "args": ["-m", "padstats_mcp"],
      "env": {
        "PADSTATS_API_KEY": "YOUR_API_KEY",
        "PADSTATS_API_BASE_URL": "https://api.padstats.io"
      }
    }
  }
}

Restart Cursor or reload MCP servers after saving the config.

Codex setup

Codex can connect to padstats-mcp as a local stdio MCP server. You can configure it through the app UI, the Codex CLI, or direct edits to the config file.

Config file locations:

• Windows: C:\Users\<you>\.codex\config.toml
• macOS/Linux: ~/.codex/config.toml

Add:

[mcp_servers.padstats]
command = "python"
args = ["-m", "padstats_mcp"]

[mcp_servers.padstats.env]
PADSTATS_API_KEY = "YOUR_API_KEY"
PADSTATS_API_BASE_URL = "https://api.padstats.io"
PADSTATS_MCP_MAX_NUM_COMPS = "3"
PADSTATS_MCP_MAX_CRIME_LIMIT = "50"
PADSTATS_MCP_READ_TIMEOUT_S = "120"

On Windows, use a literal string if you need an explicit Python path:

[mcp_servers.padstats]
command = 'C:\Python313\python.exe'
args = ["-m", "padstats_mcp"]

Equivalent Codex CLI setup:

codex mcp add padstats \
  --env PADSTATS_API_KEY=YOUR_API_KEY \
  --env PADSTATS_API_BASE_URL=https://api.padstats.io \
  --env PADSTATS_MCP_MAX_NUM_COMPS=3 \
  --env PADSTATS_MCP_MAX_CRIME_LIMIT=50 \
  --env PADSTATS_MCP_READ_TIMEOUT_S=120 \
  -- python -m padstats_mcp

After changing Codex MCP config, fully quit Codex, reopen it, and start a new chat. Already-open sessions may not see newly attached MCP tools.

Verify in an MCP client

Use this first prompt in a new MCP-enabled session:

Use the PadStats MCP tool padstats_mcp_info.
Tell me the active API base URL host, max comparables, max crime limit,
package version, and available PadStats tools.
Do not browse or use shell commands.

Expected behavior:

• The client calls padstats_mcp_info.
• meta.mcp.api_call_made is false.
• The API host and MCP caps match your config.
• No PadStats credits are consumed.

Then run a small live tool call with conservative caps:

Use PadStats MCP to estimate the sale value for 470 Manor St, Lancaster, PA 17603.
Use exactly 3 comparables.
Subject details: 4 bedrooms, 2 bathrooms, 1,427 sqft living area,
1,742 sqft lot, built in 1860, townhome.
Return the estimate, confidence interval, external comps, and meta.mcp.request_echo.
Do not browse or use shell commands.

Successful valuation, rental, risk, crime, census, and comprehensive calls use the normal PadStats API and can consume credits.

Source-checkout demo

If you are developing from an intelligence-api source checkout, you can list tools without making a PadStats API call:

python scripts\mcp_client_demo.py

The demo client starts padstats-mcp over stdio, initializes an MCP session, and prints the tools a real agent client can see.

Call the diagnostic info tool without an API key or PadStats API request:

Remove-Item Env:PADSTATS_API_KEY -ErrorAction SilentlyContinue
python scripts\mcp_client_demo.py --tool padstats_mcp_info --arguments-json '{}'

To make a live tool call, set your API key and pass JSON arguments. This can consume credits.

$env:PADSTATS_API_KEY = "YOUR_API_KEY"
$env:PADSTATS_API_BASE_URL = "https://api.padstats.io"

$payload = @{
  location = @{ address = "536 SW 2nd St, Miami, FL 33130" }
  property_fields = @{
    bedrooms = 8
    bathrooms = 4
    living_area = 4298
    lot_size = 7500
    year_built = 1981
  }
  search_params = @{ num_comps = 3 }
} | ConvertTo-Json -Depth 8 -Compress

python scripts\mcp_client_demo.py --tool property_avm --arguments-json $payload

Available tools

MCP tool	Best used for
padstats_mcp_info	Confirm active MCP config, limits, API base URL host, and tool availability without consuming credits.
property_avm	Residential sale value, confidence interval, and sale comparables.
rental_avm	Monthly rent estimate and rent comparables.
multifamily_avm	Whole-building multifamily valuation.
comprehensive_report	Multi-section property diligence report.
flood_zone_lookup	FEMA flood zone and SFHA status.
storm_surge_risk	Hurricane storm surge zone and depth category.
fire_risk_lookup	Wildfire risk category and annual chance.
sinkhole_risk_lookup	Sinkhole susceptibility and risk-zone status.
natural_hazards_lookup	County and tract hazard risk indices.
crime_data_lookup	Nearby crime summary and optional incidents.
census_data_lookup	ACS variables by address, coordinates, or GEOID.
socioeconomic_data_lookup	PadStats socioeconomic indices and grades.

Batch AVM tools are intentionally not exposed in the first MCP version.

Example prompts

Use the PadStats MCP server to call padstats_mcp_info.
Tell me the active API base URL host, max comparables, max crime limit,
and available PadStats tools. Do not browse or use shell commands.

Expected tool: padstats_mcp_info

Estimate the sale value for 536 SW 2nd St, Miami, FL 33130.
Use 3 comparables. The property has 8 bedrooms, 4 bathrooms,
4,298 sqft, 7,500 sqft lot, and was built in 1981.

Expected tool: property_avm

Check flood zone, storm surge, fire, and sinkhole risk for
901 Ocean Dr, Naples, FL 34102.

Expected tools: flood_zone_lookup, storm_surge_risk, fire_risk_lookup, and sinkhole_risk_lookup, or a scoped comprehensive_report.

Summarize recent crime within 1 mile of 470 Manor St, Lancaster, PA 17603.
Do not fetch individual incident details.

Expected tool: crime_data_lookup with include_crime_details=false and a low limit when the user wants summary-first output. include_crime_details=false suppresses extended fields on returned records; the API can still return basic crime rows up to limit.

Build a concise report for 470 Manor St, Lancaster, PA 17603 with property AVM,
flood zone, crime summary, and socioeconomic only. Do not request extra sections.

Expected tool: comprehensive_report with requests=["property-avm","flood-zone","crime-data","socioeconomic"], include_crime_summary=true, and include_crime_details=false. The MCP schema accepts crime-summary as an alias and normalizes it to crime-data.

Streamable HTTP

Stdio is the recommended default for local desktop clients because the API key stays on the user's machine. Streamable HTTP is available for internal or single-tenant hosted usage:

PADSTATS_API_KEY="YOUR_API_KEY" \
PADSTATS_MCP_TRANSPORT="streamable-http" \
PADSTATS_MCP_HTTP_HOST="127.0.0.1" \
PADSTATS_MCP_HTTP_PORT="8765" \
PADSTATS_MCP_HTTP_PATH="/mcp" \
padstats-mcp

Do not expose a multi-tenant hosted MCP server publicly unless you have designed separate hosted auth, tenant isolation, abuse controls, and usage caps.

Response shape

MCP tools return the same structured envelope as the API:

{
  "data": {},
  "meta": {
    "credits": {
      "charged": 45,
      "remaining": 4955,
      "pool": "api"
    },
    "mcp": {
      "tool": "property_avm",
      "api_call_made": true,
      "api_method": "POST",
      "api_path": "/v1/avm/property",
      "request_echo": {
        "location": {"address": "536 SW 2nd St, Miami, FL 33130"},
        "search_params": {"radius_mi": 5.0, "num_comps": 3},
        "property_fields": {"bedrooms": 8, "bathrooms": 4.0}
      },
      "limits": {"max_num_comps": 3}
    }
  },
  "error": null,
  "status_code": 200,
  "endpoint": "/v1/avm/property"
}

meta.mcp is added by the MCP adapter. It tells the agent which tool ran, whether the public API was called, which API path was used, which normalized request fields were sent, and which MCP-side caps were active. Agents should inspect error before relying on data, use meta.mcp.request_echo to confirm field mapping such as condition score, and surface meta.credits when a workflow may consume multiple calls.

Some MCP clients validate typed tool arguments before the PadStats adapter receives the request. Those pre-call validation failures can appear as client/tool execution errors instead of the normalized response envelope. For example, property_fields.condition=6.0 is rejected because condition must be a numeric score from 0 to 5 inclusive. Agents should report that validation error and ask for corrected input rather than retrying with guessed values.