MCP server

Mapsdata exposes an MCP server over Streamable HTTP. It uses the same account, credits, searches, enrichment pipeline, and results as the dashboard and REST API.

MCP server URL

https://www.mapsdata.io/mcp

Authentication

Add the server URL, sign in to Mapsdata in your browser, review the requested access, and click Allow access. The client receives a revocable OAuth token. Mapsdata supports OAuth 2.1 authorization-code flow with PKCE, dynamic client registration, refresh-token rotation, protected-resource metadata, and token revocation.

Connect a client

Open the custom MCP setup

In ChatGPT, click the Plugins icon on the left-hand side (the @-shaped icon with a plug inside), then click Browse directory. Click Add to open the dropdown, then choose Add custom MCP server.

Enter the server details

Enter the fields below, keep Connection set to Server URL, and select OAuth for authentication.Name

Mapsdata

Server URL

https://www.mapsdata.io/mcp

Authentication

OAuth

Create the connector, choose Sign in, then sign in to Mapsdata and click Allow access. Mapsdata will appear on the left-hand side. Start a chat and type @Mapsdata to use it.

Open Connectors

Go to Customize → Connectors. Click Add to open the dropdown, then select Add custom connector.

Enter the connector details

Enter the fields below and click Continue. Claude will detect Mapsdata OAuth automatically.Name

Mapsdata

MCP server URL

https://www.mapsdata.io/mcp

Add the connector, sign in to Mapsdata in the browser, and click Allow access. Then enable Mapsdata from the connector picker in your conversation.

Add the MCP server

Run this command in your terminal.

claude mcp add --transport http --scope user mapsdata https://www.mapsdata.io/mcp

Authenticate

Start Claude Code, enter /mcp, select mapsdata, and choose Authenticate. Sign in to Mapsdata in the browser and allow access.

Start with a safe request

Ask Claude to check your Mapsdata account first. It will show the maximum credit cost and ask before starting a search or enrichment.

Add the server configuration

Open Customize in Cursor, click MCPs, then click New MCP Server and merge this entry into mcp.json.

{
  "mcpServers": {
    "mapsdata": {
      "type": "http",
      "url": "https://www.mapsdata.io/mcp"
    }
  }
}

Save the file, enable Mapsdata, and choose Authenticate if prompted. Complete the Mapsdata sign-in in your browser and click Allow access.

Verify the tools

Confirm that Mapsdata shows as connected and its tools are listed. Restart Cursor if the tool list does not refresh.

Add the MCP server

Run this command. Codex will register an OAuth client for Mapsdata.

codex mcp add mapsdata --url https://www.mapsdata.io/mcp --oauth-client-registration dcr

Run the command below, sign in to Mapsdata in the browser, and click Allow access.

codex mcp login mapsdata --oauth-client-registration dcr

Verify the connection

Run codex mcp list and confirm that mapsdata is enabled with OAuth authentication.

Open the MCP configuration

Go to Customizations → Installed, scroll to MCP Servers, and click Copy config file path. Open that file.

Add Mapsdata

Merge this entry into the existing configuration and save it.

{
  "mcpServers": {
    "mapsdata": {
      "serverUrl": "https://www.mapsdata.io/mcp"
    }
  }
}

Restart and authenticate

Quit and reopen Antigravity. Go back to the MCP Servers section, choose Authenticate for Mapsdata, and finish signing in in the browser.

Tools

Account and discovery

Tool	Purpose	Credits
`check_account`	Read the plan, remaining credits, search limit, and active-job count.	0
`find_locations`	Resolve a city or region to the canonical label and country code required by a search.	0
`find_categories`	Find canonical Google business categories for a niche.	0
`search_businesses`	Start one Google Maps discovery job, with optional contact enrichment.	Up to `max_results`
`list_searches`	List dashboard, REST API, and MCP discovery jobs, optionally scoped by source.	0
`search_status`	Read one search’s status, result count, and reserved credits.	0
`get_search_results`	Read a page of enriched businesses already found.	0
`get_business`	Read one complete business record by its result ID.	0

Supplied-business enrichment

Tool	Purpose	Credits
`enrich_businesses`	Enrich supplied business names and absolute website URLs.	1 per business
`list_enrichments`	List supplied-business enrichment jobs.	0
`enrichment_status`	Read one enrichment job’s status and reserved credits.	0
`get_enrichment_results`	Read a page of supplied-business results.	0

All tools return structured output. Read-only tools are marked read-only in their MCP annotations. search_businesses and enrich_businesses are marked destructive because they reserve credits, even though their idempotency keys make safe retries possible. To retrieve an existing search, call list_searches. It returns the newest search first and includes searches created in the Mapsdata website by default. Pass scope: "dashboard" or scope: "integration" to narrow the list. Use search_status for job details, get_search_results for its businesses, and get_business when you need one complete record by ID.

Recommended search workflow

Check the account

Call check_account. Do not request more than both credits_remaining and max_results_per_search.

Resolve the location

Call find_locations and select one returned location. Copy its label and country_code into search_businesses.

Confirm the cost

Tell the user the maximum number of credits the search can reserve. Call search_businesses only after approval, setting confirmed_credit_cost to exactly the same number as max_results.

Poll and paginate

Poll search_status every 5–10 seconds. Read live pages with get_search_results; after the job reaches completed, fetch every page again until has_more is false.

For supplied websites, use the same pattern: check_account, state the exact number of businesses and credits, obtain approval, then call enrich_businesses with the matching confirmed_credit_cost.

Credit and retry safety

Both credit-spending tools reject a call when confirmed_credit_cost does not match the maximum charge.
Use a stable, unique idempotency_key for each logical creation request. If a network call times out, retry the same body and key.
Never retry an uncertain creation with a new key; that can create and charge a second job.
Reading catalogs, account state, job status, lists, and results consumes no credits.
Result pages are capped at 100 leads in MCP to keep agent context bounded. Continue while has_more is true.

Getting started

Endpoints

Reference

Authentication

Connect a client

Tools

Account and discovery

Supplied-business enrichment

Recommended search workflow

Credit and retry safety

​Authentication

​Connect a client

​Tools

​Account and discovery

​Supplied-business enrichment

​Recommended search workflow

​Credit and retry safety

Authentication

Connect a client

Tools

Account and discovery

Supplied-business enrichment

Recommended search workflow

Credit and retry safety