CommunityScale Docs

Connect an AI assistant (MCP)

The CommunityScale MCP server lets an AI assistant query the same housing data that powers our dashboards, instead of reading our web pages. It speaks the Model Context Protocol, the open standard Claude, ChatGPT, Codex and most agent frameworks use to call outside tools.

Endpoint

SettingValue
URLhttps://api.communityscale.io/mcp/v1
TransportStreamable HTTP
Sign-inOAuth 2.1 with your CommunityScale account; your AI tool opens the sign-in page for you
AccessRead-only
Rate limit120 requests per minute for each signed-in connection

You need a CommunityScale account. If you don't have one, the sign-in page lets you create one, or you can create one now.

Connect your AI tool

Claude (web and desktop)

claude.ai/directory/communityscale

Claude Code

If you sign in to Claude Code with your Claude account, a CommunityScale connector you added in Claude is already available; type /mcp to see it. Otherwise, add the server directly:

claude mcp add --transport http communityscale https://api.communityscale.io/mcp/v1

Then type /mcp inside Claude Code to sign in. The tools are available in every session afterward.

Or install the CommunityScale plugin, which adds the same connection and a skill that teaches Claude how to answer with our data:

/plugin marketplace add CommunityScale/communityscale-mcp-public
/plugin install communityscale@communityscale

ChatGPT

  1. Open ChatGPT's plugins page.
  2. Select the plus button, then Add custom MCP server.
  3. Name it CommunityScale and paste https://api.communityscale.io/mcp/v1 as the URL.
  4. Choose OAuth, review the warning, and select Create as a plugin.
  5. Sign in through the OAuth prompt.

Your account and workspace settings decide whether you can add a custom MCP server.

Codex CLI

codex mcp add communityscale --url https://api.communityscale.io/mcp/v1
codex mcp login communityscale

Your own agent

Anything that speaks MCP over Streamable HTTP can connect. The server publishes its OAuth details at https://api.communityscale.io/.well-known/oauth-protected-resource/mcp/v1, and the sign-in service supports dynamic client registration, so an MCP client can register and sign in without any setup on our side. Both the Claude API and the OpenAI Responses API accept remote MCP servers by URL; a custom agent gets the same tools by pointing at the endpoint and completing the OAuth flow.

Tools

ToolWhat it does
findEntityResolves a place name or FIPS code to a municipality or county, with a link to its dashboard and the keys the other tools take. Call it first.
getForecastOur computed dashboard figures for a place: housing supply targets, cost burden by income group, affordability, AMI thresholds and population forecasts. Takes a place name or a geoid.
exploreDataTrends and custom breakdowns from our curated sources, sorted as you ask: income, home prices and affordability over time, wages and inflation, population, building permits, HUD income limits and survey-weighted ACS microdata.
dataSchemaThe fields exploreData accepts for a source, with the data dictionary entry for the data behind it: publisher, license, datasets and latest vintage.
findLakeTablesFinds lake tables to query by a word in their name, columns or description, each linked to its dictionary page. Each table lists its partition columns and the columns that match, with each column's type, and what each matching column means.
queryLakeRuns a read-only SQL query over the tables of the data lake, such as ACS at any geography down to block groups, with joins. A ranking names its places by joining app.geo_search. The result gives each column's type.
searchDataDictionarySearches the data dictionary for datasets on a topic and names the exploreData source and lake tables that can query each one. Can include the top matches' variables.
describeDatasetThe variables of one dataset in the data dictionary, a page at a time, with each one's definition and unit, or only the variables that match words you give.
getReportThe published dashboard report for a municipality or county, as Markdown. Takes a place name or a geoid.

The server also sends the assistant our metric definitions, analysis recipes and data cautions, so it calculates cost burden, AMI bands and survey-weighted estimates the way we do. Every exploreData result names the source it came from.

What to ask

  • "What share of renter households in Worcester, Massachusetts spend more than half their income on housing?"
  • "How many homes does Rockland, Maine need to add by its target year, and what drives that number?"
  • "How have home values and the income needed to buy a home changed in Union County, North Carolina since 2015?"
  • "Which datasets does CommunityScale have on building permits, and how current are they?"

Plugin and directory listings

The server is listed in Claude's connectors directory at claude.ai/directory/communityscale. The Claude plugin, the ChatGPT plugin package and the skill that teaches an assistant to use these tools live in CommunityScale/communityscale-mcp-public. That repository and this page describe the same server, so the tool list here and the plugin's skill and test prompts there change together.

Privacy

For each request the server records your IP address, a one-way fingerprint of your sign-in token (used to apply the rate limit), which tool ran, whether it succeeded and how long it took. It does not record what you asked, the arguments a tool received, or your sign-in token itself. Sign-in is handled by Clerk, our account provider. The data the tools return comes from public sources and our published analysis; nothing you send is used to change it. See our privacy policy for how we handle account information, and write to us there with any question.

For crawlers and automated agents

Please use the MCP server rather than crawling dashboard pages for data. The tools return the same figures, with definitions and sources, in a form an agent can use directly. A plain-text index of this documentation is at docs.communityscale.io/llms.txt.

Previous page
Overview
Next page
Housing affordability