MCP Tool Reference

Complete reference for all 8 tools available through PrairieCloud's MCP server. Each tool maps to a PrairieCloud REST API endpoint and returns structured Census data.

For setup instructions, see the MCP Quickstart.

Authentication

PrairieCloud's MCP server supports two authentication methods:

Method	Format	Use When
Authorization header (preferred)	`Authorization: Bearer pck_live_xxxxx`	Cursor, Windsurf, custom MCP clients
URL query parameter	`?api_key=pck_live_xxxxx`	Claude Desktop (connectors can't send custom headers)

Both methods use your PrairieCloud API key. MCP access requires a paid plan (Pioneer, Pro, Business, or Enterprise).

Connection access and geography workflow access are separate checks:

MCP server access: Pioneer, Pro, Business, Enterprise
Direct tract/block group data lookup via MCP: Any MCP-enabled plan when you provide a specific FIPS/name
Tract wildcard or inline-geometry workflows via MCP: Pro+
Block-group wildcard or inline-geometry workflows via MCP: Business+

For detailed setup instructions per platform, see the MCP Quickstart.

Data Tools

These tools retrieve Census data. They're what Claude uses to answer your questions about population, income, housing, and other statistics.

`get_census_data`

Retrieve U.S. Census Bureau data for specific variables and geographies. This is the most commonly used tool — most questions about Census statistics will use it.

Maps to: GET /v1/data

Parameters

Name	Type	Required	Default	Description
`variables`	string	✅	—	Comma-separated variable names. Use human-readable names like `income_median_household`, `pop_total`. Call `search_variables` first if unsure of the exact name. Max 50 per request.
`geo`	string	✅	—	Comma-separated geography specifiers. Formats: `state:TX`, `county:48201`, `county:Harris County, TX`, `metro:12420`, `nation:us`, `tract:48201311100`, `tract:Dallas-Fort Worth` (metro smart resolution), `tract:TX-7` (congressional district smart resolution), `block_group:482013111001`, `block_group:Harris County, TX`. Max 25 per request. Direct lookups by specific FIPS/name are available on any MCP-enabled plan; wildcard/smart expansion starts at Pro for tracts and Business for block groups.
`dataset`	string		`acs5`	`acs5` (5-Year estimates, more geographies) or `acs1` (1-Year estimates, most current, larger geos only).
`vintage`	integer		latest	Data year (2005–2024). Omit for the latest available.
`include_moe`	boolean		`false`	Include margin of error values. Default `false` to save context window tokens. Set `true` for statistical analysis.
`include_geometry`	boolean		`false`	Include GeoJSON boundary polygons (20m resolution) in the response. Enables single-call map/choropleth visualization — data and boundaries together. Requires Pro tier or above.

Example

Ask Claude:

What's the median household income in Harris County, Texas?

Claude calls:

{
  "tool": "get_census_data",
  "arguments": {
    "variables": "income_median_household",
    "geo": "county:Harris County, TX"
  }
}

Response:

{
  "data": {
    "county:48201": {
      "name": "Harris County, Texas",
      "geo_type": "county",
      "variables": {
        "income_median_household": {
          "label": "Median household income (dollars)",
          "estimate": 61705,
          "unit": "dollar"
        }
      }
    }
  },
  "metadata": {
    "dataset": "acs5",
    "vintage": 2024,
    "source": "U.S. Census Bureau, American Community Survey 5-Year Estimates",
    "variables_requested": 1,
    "geographies_returned": 1
  }
}

Geometry Example

Ask Claude:

Show me a map of population by tract in Denton County, Texas.

Claude calls:

{
  "tool": "get_census_data",
  "arguments": {
    "variables": "pop_total",
    "geo": "tract:Denton County, Texas",
    "include_geometry": true
  }
}

Returns all 193 tracts with population data and GeoJSON MultiPolygon boundaries in a single response — everything needed to render a choropleth map without any additional API calls.

Single-call mapping

include_geometry=true is a key differentiator versus the raw Census API, which has no geometry at all and forces separate calls to TIGERweb's ArcGIS endpoint. PrairieCloud returns data and boundaries together.

`compare_geographies`

Compare Census data across multiple geographies side-by-side. Use this when comparing statistics between states, counties, or metros.

Maps to: GET /v1/compare

Parameters

Name	Type	Required	Default	Description
`variables`	string	✅	—	Comma-separated variable names to compare.
`geos`	string	✅	—	Comma-separated geography specifiers (2–10 locations).
`dataset`	string		`acs5`	`acs5` or `acs1`.
`vintage`	integer		latest	Data year (2005–2024).

Example

Ask Claude:

Compare the poverty rate and median income in Dallas County vs Travis County, Texas.

Claude calls:

{
  "tool": "compare_geographies",
  "arguments": {
    "variables": "income_median_household",
    "geos": "county:Dallas County, TX,county:Travis County, TX"
  }
}

Response:

{
  "data": {
    "county:48113": {
      "name": "Dallas County, Texas",
      "geo_type": "county",
      "variables": {
        "income_median_household": {
          "label": "Median household income (dollars)",
          "estimate": 57617,
          "unit": "dollar"
        }
      }
    },
    "county:48453": {
      "name": "Travis County, Texas",
      "geo_type": "county",
      "variables": {
        "income_median_household": {
          "label": "Median household income (dollars)",
          "estimate": 85205,
          "unit": "dollar"
        }
      }
    }
  },
  "metadata": {
    "dataset": "acs5",
    "vintage": 2024,
    "source": "U.S. Census Bureau, American Community Survey 5-Year Estimates",
    "variables_requested": 1,
    "geographies_returned": 2
  }
}

`get_timeseries`

Get historical Census data for a variable across multiple years. Use this for questions about trends and changes over time.

Maps to: GET /v1/timeseries

Parameters

Name	Type	Required	Default	Description
`variable`	string	✅	—	Single variable name.
`geo`	string	✅	—	Single geography specifier.
`dataset`	string		`acs5`	`acs5` or `acs1`.
`start_year`	integer		earliest	First year of range (2005–2024).
`end_year`	integer		latest	Last year of range (2005–2024).

Example

Ask Claude:

How has the population of Texas changed since 2015?

Claude calls:

{
  "tool": "get_timeseries",
  "arguments": {
    "variable": "pop_total",
    "geo": "state:TX",
    "start_year": 2015
  }
}

Response:

{
  "data": {
    "state:48": {
      "name": "Texas",
      "geo_type": "state",
      "timeseries": [
        { "vintage": 2015, "estimate": 26538614 },
        { "vintage": 2016, "estimate": 26956435 },
        { "vintage": 2017, "estimate": 27419612 },
        { "vintage": 2018, "estimate": 27885195 },
        { "vintage": 2019, "estimate": 28260856 },
        { "vintage": 2020, "estimate": 28635442 },
        { "vintage": 2021, "estimate": 29217653 },
        { "vintage": 2022, "estimate": 29527941 },
        { "vintage": 2023, "estimate": 30029572 },
        { "vintage": 2024, "estimate": 30503301 }
      ]
    }
  },
  "metadata": {
    "dataset": "acs5",
    "variable": "pop_total",
    "source": "U.S. Census Bureau, American Community Survey 5-Year Estimates"
  }
}

Dollar values are not inflation-adjusted

When viewing income or other dollar-denominated time series, keep in mind that values are in nominal dollars for each vintage year. Comparing dollar values across years requires external inflation adjustment.

Discovery Tools

These tools help Claude find the right variable names and geography keys before querying data.

`search_variables`

Search for available Census variables by keyword. Claude calls this automatically when it's unsure of the exact variable name.

Maps to: GET /v1/variables

Parameters

Name	Type	Required	Default	Description
`search`	string	✅	—	Search keyword (e.g., `income`, `poverty`, `housing`, `education`).
`topic`	string		—	Filter by topic: `core`, `demographics`, `economics`, `environment`, `equity`, `health`, `housing`, `social`, `transport`.
`unit`	string		—	Filter by unit: `count`, `dollar`, `percent`, `year`.
`limit`	integer		`20`	Max results (1–200).

Example

Ask Claude:

What poverty-related data is available?

Claude calls:

{
  "tool": "search_variables",
  "arguments": {
    "search": "poverty",
    "limit": 10
  }
}

Response:

{
  "data": [
    {
      "api_name": "poverty_below",
      "label": "Population below poverty level",
      "topic": "core",
      "unit": "count"
    },
    {
      "api_name": "poverty_under_18",
      "label": "Under 18 years below poverty level",
      "topic": "core",
      "unit": "count"
    },
    {
      "api_name": "poverty_65_and_over",
      "label": "65 years and over below poverty level",
      "topic": "core",
      "unit": "count"
    }
  ],
  "metadata": {
    "total_results": 24,
    "showing": 3
  }
}

`search_geographies`

Search for U.S. geographies by name or type. Use this to find the correct geography key when you know a place name but not its FIPS code.

Maps to: GET /v1/geographies

Parameters

Name	Type	Required	Default	Description
`search`	string	✅	—	Geography name to search (e.g., `Harris County`, `Houston`, `Texas`).
`type`	string		—	Filter by geography type: `nation`, `state`, `county`, `metro`, `cd`, `tract`, `block_group`.
`parent`	string		—	Parent geo key to scope results (e.g., `state:48` for Texas counties).
`limit`	integer		`20`	Max results (1–200).

Example

Ask Claude:

Find the FIPS code for Harris County, Texas.

Claude calls:

{
  "tool": "search_geographies",
  "arguments": {
    "search": "Harris County",
    "type": "county",
    "parent": "state:48"
  }
}

Response:

{
  "data": [
    {
      "geo_key": "county:48201",
      "name": "Harris County, Texas",
      "geo_type": "county",
      "fips": "48201"
    }
  ],
  "metadata": {
    "total_results": 1,
    "showing": 1
  }
}

`list_topics`

List all available Census data topics with variable counts. Takes no parameters.

Maps to: GET /v1/topics

Parameters

None.

Example

Ask Claude:

What kinds of Census data are available?

Claude calls:

{
  "tool": "list_topics",
  "arguments": {}
}

Response:

{
  "data": [
    { "topic_key": "core", "label": "Core Demographics", "variable_count": 98 },
    { "topic_key": "demographics", "label": "Demographics", "variable_count": 52 },
    { "topic_key": "economics", "label": "Economics", "variable_count": 48 },
    { "topic_key": "environment", "label": "Environment", "variable_count": 10 },
    { "topic_key": "equity", "label": "Equity & Vulnerability", "variable_count": 19 },
    { "topic_key": "health", "label": "Health", "variable_count": 14 },
    { "topic_key": "housing", "label": "Housing", "variable_count": 85 },
    { "topic_key": "social", "label": "Social Characteristics", "variable_count": 40 },
    { "topic_key": "transport", "label": "Transportation", "variable_count": 26 }
  ]
}

`list_datasets`

List available Census datasets with their vintage ranges. Takes no parameters.

Maps to: GET /v1/datasets

Parameters

None.

Example

Ask Claude:

What Census datasets and years are available?

Claude calls:

{
  "tool": "list_datasets",
  "arguments": {}
}

Response:

{
  "data": [
    {
      "dataset": "acs5",
      "name": "American Community Survey 5-Year Estimates",
      "vintages": "2009–2024",
      "geographies": "392,435 (7 geo levels)"
    },
    {
      "dataset": "acs1",
      "name": "American Community Survey 1-Year Estimates",
      "vintages": "2005–2024 (no 2020)",
      "geographies": "~1,700–1,900 (population ≥ 65,000)"
    }
  ]
}

Location Tools

These tools help resolve physical locations to Census geographies.

`geocode`

Find all Census geographies containing a specific location. Takes an address or lat/lng coordinates and returns the containing block group, tract, county, metro area, congressional district, state, and nation.

Maps to: GET /v1/geocode

Parameters

Parameter	Type	Required	Default	Description
`lat`	float	❌*	—	Latitude (-90 to 90). Required if `address` is not provided.
`lng`	float	❌*	—	Longitude (-180 to 180). Required if `address` is not provided.
`address`	string	❌*	—	Full street address (e.g., "1600 Pennsylvania Ave NW, Washington DC 20500"). Required if `lat`/`lng` are not provided.

*Provide either lat + lng OR address, not both.

Example (coordinates)

Ask Claude:

What Census geographies contain downtown Austin?

Claude calls:

{
  "tool": "geocode",
  "input": {
    "lat": 30.2672,
    "lng": -97.7431
  }
}

Response:

{
  "data": {
    "coordinates": {
      "latitude": 30.2672,
      "longitude": -97.7431
    },
    "geographies": {
      "block_group": {
        "geo_key": "block_group:484530011032",
        "name": "Block Group 2; Census Tract 11.03; Travis County; Texas"
      },
      "tract": {
        "geo_key": "tract:48453001103",
        "name": "Census Tract 11.03; Travis County; Texas"
      },
      "county": {
        "geo_key": "county:48453",
        "name": "Travis County, Texas"
      },
      "metro": {
        "geo_key": "metro:12420",
        "name": "Austin-Round Rock-San Marcos, TX Metro Area"
      },
      "congressional_district": {
        "geo_key": "congressional_district:4837",
        "name": "Congressional District 37 (118th Congress), Texas"
      },
      "state": {
        "geo_key": "state:48",
        "name": "Texas"
      },
      "nation": {
        "geo_key": "nation:us",
        "name": "United States"
      }
    }
  }
}

Common workflow: Address → Census data

1. geocode(lat=30.2672, lng=-97.7431)
   → returns block_group:484530011032

2. get_census_data(
     variables="income_median_household,pop_total",
     geo="block_group:484530011032"
   )
   → returns median income and population for that block group

This second step is a direct lookup for one returned block group, so any MCP-enabled plan can run it. If you ask for all block groups under a parent geography, that wildcard/smart-expansion workflow requires **Business or Enterprise**. On **Pro**, use the returned tract for expansion workflows.

Notes

Available to all tiers (Free+) — this is a discovery tool
Geocoding itself is available to all tiers, but follow-on data calls still honor your plan. Direct lookups for the returned tract or block group are allowed on MCP-enabled plans; wildcard expansion, inline geometry, and boundary access follow the tier rules above.
Address geocoding uses the Census Bureau geocoder and may be temporarily unavailable. If it fails, use lat/lng coordinates instead.
The lat/lng path uses PostGIS spatial lookups against 331,000+ boundary polygons and is always available
Not all geography types may be present — a point in rural Alaska might not fall within a metro area

Response Format

All MCP tools return JSON in a standard envelope.

Data tool responses

Data tools (get_census_data, compare_geographies, get_timeseries) return:

{
  "data": {
    "<geo_key>": {
      "name": "Geography Name",
      "geo_type": "state",
      "variables": {
        "<variable_name>": {
          "label": "Human-readable label",
          "estimate": 12345,
          "unit": "count"
        }
      }
    }
  },
  "metadata": {
    "dataset": "acs5",
    "vintage": 2024,
    "source": "U.S. Census Bureau, American Community Survey 5-Year Estimates",
    "variables_requested": 1,
    "geographies_returned": 1
  }
}

When include_moe is set to true, each variable also includes:

margin_of_error — numeric margin of error value (90% confidence interval)
moe_annotation — Census annotation flag, if present

By default, margin of error fields are stripped from responses to reduce token usage.

Discovery tool responses

Discovery tools (search_variables, search_geographies, list_topics, list_datasets) return:

{
  "data": [ ... ],
  "metadata": {
    "total_results": 42,
    "showing": 20
  }
}

Error Messages

When something goes wrong, the MCP server returns a structured error with guidance on how to fix it:

{
  "isError": true,
  "error": "Variable 'median_income' not found. Did you mean 'income_median_household'? Use search_variables to find the correct name."
}

Claude uses these error messages to self-correct — for example, by calling search_variables to find the right name.

Common errors

Error	Cause	What happens next
Variable not found	Incorrect variable name	Claude calls `search_variables` to find the right name
Geography not found	Invalid geo key	Claude calls `search_geographies` to look up the correct key
No data for vintage	Variable doesn't exist in that year	Claude tries a different vintage
ACS 1-Year not available	Geography has population < 65,000	Claude switches to `dataset: "acs5"`
Vintage 2020 not available (ACS 1-Year)	COVID-19 data collection gap	Claude uses 2019 or 2021 instead
Too many variables	More than 50 variables in one request	Claude splits into multiple calls
Too many geographies	More than 25 geographies in one request	Claude splits into multiple calls
Rate limit exceeded	Monthly quota used up	Returns a retry-after interval
MCP access requires a paid plan	Free tier API key	You need to upgrade your plan

Rate Limits

MCP tool calls consume the same monthly quota as REST API calls. There is no separate MCP billing or quota.

One tool call = one API request against your monthly limit
Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are tracked the same way
If you hit your quota, Claude will receive a rate limit error and inform you

Check your current usage at dashboard.prairiecloud.io.

Plan	Monthly Requests	MCP Access
Free	1,000	❌ Not available
Pioneer ($19/mo)	50,000	✅
Pro ($49/mo)	500,000	✅
Business ($299/mo)	2,000,000	✅
Enterprise	Custom	✅

Tips for Better Results

Be specific. "What's the median household income in Travis County, Texas for 2022?" gives better results than "income data."
Ask Claude to search first. If you're not sure what data exists, ask "What variables are available about education?" before requesting specific data.
Use comparisons. "Compare X in A vs B" naturally maps to the compare_geographies tool and gives you a clean side-by-side view.
Ask about trends. "How has X changed since 2015?" maps to get_timeseries and shows historical context.
Request margin of error when it matters. For statistical analysis or small-geography data, ask Claude to include margin of error in the response.

Next Steps

MCP Quickstart — Set up Claude Desktop with PrairieCloud
Data Guide — Understand datasets, vintages, and variable naming conventions
API Reference — REST API docs for code-based access

Authentication​

Data Tools​

get_census_data​

Parameters​

Example​

Geometry Example​

compare_geographies​

Parameters​

Example​

get_timeseries​

Parameters​

Example​

Discovery Tools​

search_variables​

Parameters​

Example​

search_geographies​

Parameters​

Example​

list_topics​

Parameters​

Example​

list_datasets​

Parameters​

Example​

Location Tools​

geocode​

Parameters​

Example (coordinates)​

Common workflow: Address → Census data​

Notes​

Response Format​

Data tool responses​

Discovery tool responses​

Error Messages​

Common errors​

Rate Limits​

Tips for Better Results​

Next Steps​

Authentication

Data Tools

`get_census_data`

Parameters

Example

Geometry Example

`compare_geographies`

Parameters

Example

`get_timeseries`

Parameters

Example

Discovery Tools

`search_variables`

Parameters

Example

`search_geographies`

Parameters

Example

`list_topics`

Parameters

Example

`list_datasets`

Parameters

Example

Location Tools

`geocode`

Parameters

Example (coordinates)

Common workflow: Address → Census data

Notes

Response Format

Data tool responses

Discovery tool responses

Error Messages

Common errors

Rate Limits

Tips for Better Results

Next Steps