AI agents

CRM 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.

A list of addresses · Tools: geocode_address, get_usage · 1 lookup per address that resolves. Addresses that do not match are not charged.

Example prompt

“Clean up these 25 lead addresses from our CRM export. Give me the normalized address and coordinates for each, and list the ones I need to fix by hand.”

Or pick the crm_address_cleanup prompt from the Isopleth MCP server in your client.

How it works

Call get_usage and confirm the list fits in the remaining lookups (one per address that resolves).
Call geocode_address once per address, a few at a time, within the plan's rate limit. On a rate_limited or daily_cap_reached error, wait as told rather than retrying at once.
Clean: the address resolved. Keep normalized_address, lat, lng and accuracy. An accuracy below 1 means the geocoder found more than one candidate, so put it in review too.
Review: address_not_found, PO boxes, addresses outside the US, and inputs that are only a city or ZIP. Keep timeouts and upstream errors in a separate retry list.
Coordinates come from the US Census geocoder, placed along the street from the house-number range, not rooftop points. Say so in the output.

Fields used

No data fields: this template uses geocode_address, which returns lat, lng, normalized_address, accuracy, accuracy_type and precision_note.

Tool call

What the agent sends to geocode_address:

{
  "address": "350 5th Ave, New York, NY"
}

Output

A clean table (input, normalized address, lat, lng, accuracy), a review queue with the reason for each row, and a retry list.

SKILL.md

Save this as isopleth-crm-address-cleanup/SKILL.md in your agent's skills folder (for Claude Code, ~/.claude/skills/), or download it.

---
name: isopleth-crm-address-cleanup
description: 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. Uses the Isopleth MCP server (https://api.isopleth.dev/mcp).
---

# CRM 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.

## Requirements

- The Isopleth MCP server connected at `https://api.isopleth.dev/mcp` with an API key in the `Authorization: Bearer` header (see https://isopleth.dev/docs/mcp).
- Tools used: `geocode_address`, `get_usage`.
- Cost: 1 lookup per address that resolves. Addresses that do not match are not charged.

## Steps

1. Call get_usage and confirm the list fits in the remaining lookups (one per address that resolves).
2. Call geocode_address once per address, a few at a time, within the plan's rate limit. On a rate_limited or daily_cap_reached error, wait as told rather than retrying at once.
3. Clean: the address resolved. Keep normalized_address, lat, lng and accuracy. An accuracy below 1 means the geocoder found more than one candidate, so put it in review too.
4. Review: address_not_found, PO boxes, addresses outside the US, and inputs that are only a city or ZIP. Keep timeouts and upstream errors in a separate retry list.
5. Coordinates come from the US Census geocoder, placed along the street from the house-number range, not rooftop points. Say so in the output.

## Output

A clean table (input, normalized address, lat, lng, accuracy), a review queue with the reason for each row, and a retry list.

Every value carries its source, license and attribution. Keep the source next to each value, and show the attributions if you share the results.

Connect your agent

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).

Open Plugins in ChatGPT, select +, then Add custom MCP server. (Older layouts: Settings → Apps → Create, with developer mode on.)
Name it Isopleth and enter the server URL https://api.isopleth.dev/mcp.
Choose OAuth for authentication and leave the client ID and secret blank. ChatGPT registers itself.
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.
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.

Go to Customize → Connectors (formerly Settings → Connectors), select Add, then Add custom connector.
Name it Isopleth and enter https://api.isopleth.dev/mcp. Keep the detected sign-in settings and leave the OAuth client fields blank.
Select Connect, sign in to Isopleth with your email and choose Allow access.
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

Approving an app gives it access to Isopleth's MCP tools only. It can't see your API keys or billing, and its token is refused by the REST API.
Lookups made through an app count against your plan, with the same rate limit and daily cap as your API keys. All your connected apps share one rate limit.
Access tokens expire after an hour and the app renews them quietly. Renewal stops after 30 days without use.
See and disconnect apps any time under Connected apps on your dashboard. A disconnected app loses access immediately.
Technical details: OAuth 2.1 with PKCE (S256), dynamic client registration and client ID metadata documents, and discovery at https://api.isopleth.dev/.well-known/oauth-protected-resource/mcp.

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.