API

Connect an AI agent

Last updated: September 2, 2026

MapsData is a remote MCP server, so an AI assistant can build your lead lists directly. Connect it once and you can ask Claude or another agent to find plumbers in Texas, and it will check the category, start the scrape, and hand you the file when it is done.

MCP is the Model Context Protocol, an open standard for giving an assistant access to a tool. Our server is at:

https://mapsdata.ai/mcp

Included on the Scale plan, same as the REST API, and it uses the same API keys. Scrapes started by an agent count against the same monthly allowance as everything else.

Connecting

Authentication is a bearer token: your MapsData API key, created in Settings. See authentication for how keys work.

Claude Code

claude mcp add --transport http mapsdata https://mapsdata.ai/mcp \
  --header "Authorization: Bearer mdk_live_..."

Cursor

In ~/.cursor/mcp.json, or the project's .cursor/mcp.json:

{
  "mcpServers": {
    "mapsdata": {
      "url": "https://mapsdata.ai/mcp",
      "headers": {
        "Authorization": "Bearer mdk_live_..."
      }
    }
  }
}

Anything else

Any client that speaks streamable HTTP MCP and lets you set a header will work. The server is stateless: it issues no session id, and every call is a single POST.

Hosted connectors

Directories like Claude.ai's have nowhere to put a header, so they use OAuth instead. MapsData supports that: dynamic client registration, an authorization code flow with PKCE, and rotating refresh tokens. Point the connector at https://mapsdata.ai/mcp and it discovers the rest, then sends you to a consent screen that names the application and states plainly that approving it lets that application spend your monthly lead allowance.

Approved connections appear in Settings beside your API keys, and disconnecting one takes effect immediately.

OAuth is rolling out. If a connector reports that authorization is unavailable, it is not enabled for your workspace yet. Use a client that accepts an Authorization header in the meantime, and talk to us if you need the connector path.

Tools

Tool	What it does
`mapsdata_search_categories`	Find the exact Google Maps category to scrape
`mapsdata_list_regions`	Valid region names for a country
`mapsdata_get_usage`	Allowance left this cycle, and the per-scrape ceiling
`mapsdata_start_scrape`	Start a scrape. Supports a dry run.
`mapsdata_get_scrape`	Check one scrape
`mapsdata_list_scrapes`	Recent scrapes, newest first
`mapsdata_get_download_link`	A 15-minute link to the results
`mapsdata_cancel_scrape`	Cancel a queued or running scrape

Cancel is marked destructive, so a well-behaved client will ask you before running it. That is deliberate: cancelling a running scrape still bills the leads already delivered.

A worked example

Ask for what you want in plain language:

Find me 500 plumbers in Texas with email addresses.

A well-behaved agent will confirm the category is scrapable, start the job, and then stop rather than sitting in a loop:

> mapsdata_search_categories(query: "plumb")
  ["Plumber", "Plumbing supply store"]

> mapsdata_start_scrape(query: "Plumber", states: ["Texas"],
                        total_limit: 500)
  {"job_id": "8f2c...", "status": "queued",
   "poll_after_seconds": 60,
   "next_action": "Tell the user the scrape is queued ... then STOP."}

"Started a scrape for 500 plumbers in Texas. It usually takes anywhere
 from a few minutes to a couple of hours. MapsData will email you when
 it's done, or ask me to check on it."

Later, ask it to check and fetch the file:

> mapsdata_get_scrape(job_id: "8f2c...")
  {"status": "completed", "leads_scraped": 480, "leads_with_email": 151,
   "next_action": "Call mapsdata_get_download_link."}

> mapsdata_get_download_link(job_id: "8f2c...")
  {"download_url": "https://...", "filename": "Plumber.csv",
   "expires_in_seconds": 900}

Why it will not sit and poll

A scrape runs for minutes to hours, which is an awkward shape for an assistant. Every job response carries a poll_after_seconds figure and an explicit next_action instruction telling the agent to report and stop. Agents follow a field in the response far more reliably than they follow a description, so both are there.

If an agent does loop anyway, the rate limits stop it: 120 calls a minute per key and 10 scrape submissions a minute per workspace.

When something is wrong

Tool failures come back as readable errors the agent can act on rather than as protocol faults, and they name the tool that fixes the problem. Asking for a category that does not exist tells the agent to call mapsdata_search_categories; using TX instead of Texas tells it to call mapsdata_list_regions. In practice the agent corrects itself and retries without involving you.

Safety

Your key is your workspace's quota. An agent holding it can spend the month's allowance. Use a key made for this, so you can revoke it without breaking anything else.
Read-only if you prefer. A key limited to scrape:read lets an assistant check and download existing scrapes but never start or cancel one.
Cancelling costs money. It is flagged destructive so your client asks first. Keep that confirmation on.

Try it on your own market

Create a free MapsData account and get 500 Google Maps leads with emails every month. No card needed.

Get 500 free leads a month