Introduction
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
| Setting | Value |
|---|---|
| URL | https://api.communityscale.io/mcp/v1 |
| Transport | Streamable HTTP |
| Sign-in | OAuth 2.1 with your CommunityScale account; your AI tool opens the sign-in page for you |
| Access | Read-only |
| Rate limit | 120 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)
- Open Claude's connector settings.
- Click Add custom connector.
- Name it
CommunityScaleand pastehttps://api.communityscale.io/mcp/v1as the URL. - Click Connect and sign in when prompted.
Claude Code
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.
ChatGPT
- Open ChatGPT's settings and go to Connectors.
- Under Advanced, enable Developer mode.
- Click Create, name the connector
CommunityScale, and pastehttps://api.communityscale.io/mcp/v1. - Sign in through the OAuth prompt.
Custom connectors require ChatGPT's developer mode, available on Plus and Pro plans and in Business, Enterprise and Edu workspaces.
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
| Tool | What it does |
|---|---|
findEntity | Resolves a place name or FIPS code to a CommunityScale geography, with the keys the other tools take. Call it first. |
getForecast | Our computed dashboard figures for a place: housing supply targets, cost burden by income group, affordability, AMI thresholds and population forecasts. |
exploreData | Trends and custom breakdowns from our curated sources: home values and rents, income and affordability over time, wages and inflation, population, building permits, HUD income limits and survey-weighted ACS microdata. |
dataSchema | The fields exploreData accepts for a source, with the data dictionary entry for the data behind it: publisher, license, datasets and latest vintage. |
searchDataDictionary | Searches the data dictionary for datasets on a topic and names the exploreData source that can query each one. |
describeDataset | Every variable of one dataset in the data dictionary, with its definition and unit. |
getReport | The published dashboard report for a municipality or county, as Markdown. |
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 model and view that produced it.
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?"
Privacy
The server records 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.
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.