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)
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
- Open ChatGPT's plugins page.
- Select the plus button, then Add custom MCP server.
- Name it
CommunityScaleand pastehttps://api.communityscale.io/mcp/v1as the URL. - Choose OAuth, review the warning, and select Create as a plugin.
- 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
| Tool | What it does |
|---|---|
findEntity | Resolves 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. |
getForecast | Our 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. |
exploreData | Trends 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. |
dataSchema | The fields exploreData accepts for a source, with the data dictionary entry for the data behind it: publisher, license, datasets and latest vintage. |
findLakeTables | Finds 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. |
queryLake | Runs 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. |
searchDataDictionary | Searches 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. |
describeDataset | The 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. |
getReport | The 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.