Isopleth Docs Fields TemplatesPricing Sign in Get API key
AI agents

MCP server

Isopleth runs a hosted Model Context Protocol server, so Claude, Cursor, VS Code, Codex, ChatGPT, Claude.ai and other AI agents can look up public data about any US location directly. Connect with your Isopleth sign-in or an API key; either way it uses the same plans, lookups and limits as the REST API.

Create a free account in under a minute.1,000 free lookups every month · no card
Get a free API key →

Connect

Server URL: https://api.isopleth.dev/mcp (Streamable HTTP). Two ways to authenticate:

ChatGPT

ChatGPT connects with your Isopleth sign-in, no key needed. Custom MCP servers are available on ChatGPT web for Pro, Business, Enterprise and Edu accounts (workspace admins may need to allow them).

  1. Open Plugins in ChatGPT, select +, then Add custom MCP server. (Older layouts: Settings → Apps → Create, with developer mode on.)
  2. Name it Isopleth and enter the server URL https://api.isopleth.dev/mcp.
  3. Choose OAuth for authentication and leave the client ID and secret blank. ChatGPT registers itself.
  4. Accept the risk notice and create it. ChatGPT opens the Isopleth sign-in: enter your email, open the sign-in link we send you in the same browser, and choose Allow access.
  5. Start a chat, type @ and pick Isopleth.

Claude.ai (web, desktop and mobile)

Claude connects with your Isopleth sign-in too. Custom connectors are on Pro, Max, Team and Enterprise plans; on Team and Enterprise an owner adds the connector first, then each person connects their own Isopleth account.

  1. Go to Customize → Connectors (formerly Settings → Connectors), select Add, then Add custom connector.
  2. Name it Isopleth and enter https://api.isopleth.dev/mcp. Keep the detected sign-in settings and leave the OAuth client fields blank.
  3. Select Connect, sign in to Isopleth with your email and choose Allow access.
  4. Turn Isopleth on from the connectors menu in a chat. A connector added on claude.ai also shows up in Claude Desktop and the mobile apps.

How app sign-in works

Claude Code

claude mcp add --transport http isopleth https://api.isopleth.dev/mcp --header "Authorization: Bearer $ISOPLETH_KEY"

Or skip the key: add it without the header, then run /mcp in Claude Code and choose to authenticate.

Claude Desktop

The simplest route is the connector set up on claude.ai, which Claude Desktop picks up. To use an API key instead, go through the mcp-remote bridge (needs Node.js 18 or later): open Settings → Developer → Edit Config, add this to claude_desktop_config.json, then restart Claude Desktop.

{
  "mcpServers": {
    "isopleth": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.isopleth.dev/mcp",
        "--header",
        "Authorization:${ISOPLETH_AUTH}"
      ],
      "env": {
        "ISOPLETH_AUTH": "Bearer YOUR_ISOPLETH_KEY"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Leave out headers to sign in with your Isopleth account instead of a key.

{
  "mcpServers": {
    "isopleth": {
      "url": "https://api.isopleth.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ISOPLETH_KEY"
      }
    }
  }
}

VS Code (Copilot agent mode)

Add to .vscode/mcp.json. VS Code asks for the key once and stores it securely. Without the headers block VS Code offers to sign in with your Isopleth account.

{
  "servers": {
    "isopleth": {
      "type": "http",
      "url": "https://api.isopleth.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${input:isopleth-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "isopleth-key",
      "description": "Isopleth API key",
      "password": true
    }
  ]
}

OpenAI Codex CLI

Add to ~/.codex/config.toml and export ISOPLETH_KEY in your shell.

[mcp_servers.isopleth]
url = "https://api.isopleth.dev/mcp"
bearer_token_env_var = "ISOPLETH_KEY"

Other MCP clients

Any client that supports Streamable HTTP works: server URL https://api.isopleth.dev/mcp, then either the header Authorization: Bearer <your key> or the client's OAuth sign-in. Clients that only speak stdio can use the mcp-remote bridge shown for Claude Desktop.

Tools

toolwhat it does
fetch_locationGet public-data facts for one US location, given lat+lng or a street address, and a preset and/or a list of field names. Each value comes back with its unit, status (ok, absent or failed), source and confidence. Costs 1 lookup per started block of 50 fields; nothing is charged when no field returns data.
fetch_batchGet the same preset and/or fields for several US locations in one call (up to your plan's batch size: 10 on Free, 100 on paid plans). Results are index-aligned with the input, each with its own ok flag. Costs 1 lookup per location per started block of 50 fields. Places nobody has asked about before are fetched live and can take a few seconds each, so keep batches to 10-25 new locations per call. Pass idempotency_key to retry a batch without being charged twice.
geocode_addressTurn a US street address into lat/lng plus the normalized address, using the US Census geocoder (placed along the street from the house-number range, not a rooftop). accuracy is 1 for a single match and lower when several candidates matched. Costs 1 lookup when it resolves; address_not_found is not charged.
list_presetsList the named field bundles (presets) such as terrain, flood_risk, natural_hazard, utilities, solar_siting and data_center_siting, with their field names. Free.
search_fieldsSearch the field catalog by words in the field name or description (e.g. 'flood zone', 'substation', 'wildfire', 'broadband'), optionally limited to one preset or source. Returns name, type, unit, source and description. Free.
describe_fieldsFull catalog entries for named fields: description, type, unit, source, source URL, license, attribution, refresh interval and presets. Free.
parcel_enrichGet the public parcel record for one US parcel, located by lat+lng, street address, parcel_id (from an earlier result) or apn+state: owner, situs and mailing address, land use, zoning, assessed/land/improvement value, last sale, year built, legal description, plus boundary calcs (acres, square feet, perimeter, centroid, bounding box, compactness, minimum rectangle) and the GeoJSON boundary. Columns vary by state; see parcel_coverage. Optionally pass fields and/or a preset to also compute point fields at the parcel centroid. Costs 1 lookup per matched parcel plus 1 per started block of 50 point fields; nothing is charged when no parcel matches.
parcel_searchFind parcels in one or more states by county, acreage, owner name, land-use code or words, total/land value, sale price or date, year built, ZIP, city, a bbox or a GeoJSON polygon, or generic column filters ({field, op, value} with op eq, ne, lt, lte, gt, gte, in, between, contains, starts_with, exists, missing). All filters are ANDed. Returns up to 100 parcels per page with next_cursor for the next page. Costs 1 lookup per page that returns parcels.
parcel_coverageStates with parcel data: parcel counts, counties, publisher, licence, data vintage, refresh cadence and the share of parcels with each column filled (owner, values, sale, zoning...). Free.
get_usageYour plan, its limits (batch size, requests per minute, daily cap), lookups remaining this period and recent daily usage. Free. Check it before a large batch.

Prompts

The server also offers each template as an MCP prompt. In clients that show prompts (for example as slash commands), pick one and give it a location or a list.

prompttemplate
land_readLand Read: Terrain, soil and land-cover facts for one site, every value tied to its public source.
power_readPower Read: Grid and utility context for one site: nearest transmission line and voltage, substation, power plant, gas pipeline, utility territory and water and sewer service.
hazards_readHazards Read: Flood, wetland, wildfire and severe-weather exposure for one site, cited to FEMA, USFWS, USGS, NOAA and state fire-agency sources.
insurance_book_monitoringInsurance Book Monitoring: Re-screen a list of insured properties for flood, wildfire and severe-weather exposure in batches, and route anything that crosses a threshold to manual review.
crm_address_cleanupCRM Address Cleanup: Turn a messy list of CRM or lead addresses into normalized records with coordinates, and an explicit review queue for anything that did not match.

Lookups and limits

Tool calls are metered exactly like the REST API, because they run through it: one location with up to 50 fields is 1 lookup, a geocode that resolves is 1 lookup, and one matched parcel from parcel_enrich is 1 lookup, one parcel_search page with results is 1 lookup, and list_presets, search_fields, describe_fields, parcel_coverage and get_usage are free. Your plan's requests per minute, batch size, concurrency and daily cap apply to tool calls too. Connecting and listing tools are free and do not use your per-minute requests. See Lookups and billing.

When a limit is hit, the tool returns an error with its code (for example rate_limited, daily_cap_reached or quota_exhausted) and, where relevant, retry_after_s, so the agent can wait or tell you.

Tips for agents

← PreviousAPI referenceNext →Parcels