> ## Documentation Index
> Fetch the complete documentation index at: https://www.mapsdata.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect ChatGPT, Claude, Claude Code, Cursor, Codex, Google Antigravity, and other MCP clients to Mapsdata to allow your AI agent to search for local businesses, enrich them by domain, and get back verified owner names, owner and decision-maker emails

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.

```text MCP server URL theme={null}
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

<Tabs>
  <Tab title="ChatGPT">
    <Steps>
      <Step title="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**.
      </Step>

      <Step title="Enter the server details">
        Enter the fields below, keep **Connection** set to **Server URL**, and select **OAuth** for authentication.

        **Name**

        ```text theme={null}
        Mapsdata
        ```

        **Server URL**

        ```text theme={null}
        https://www.mapsdata.io/mcp
        ```

        **Authentication**

        ```text theme={null}
        OAuth
        ```
      </Step>

      <Step title="Sign in and allow access">
        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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude">
    <Steps>
      <Step title="Open Connectors">
        Go to **Customize → Connectors**. Click **Add** to open the dropdown, then select **Add custom connector**.
      </Step>

      <Step title="Enter the connector details">
        Enter the fields below and click **Continue**. Claude will detect Mapsdata OAuth automatically.

        **Name**

        ```text theme={null}
        Mapsdata
        ```

        **MCP server URL**

        ```text theme={null}
        https://www.mapsdata.io/mcp
        ```
      </Step>

      <Step title="Sign in and allow access">
        Add the connector, sign in to Mapsdata in the browser, and click **Allow access**. Then enable Mapsdata from the connector picker in your conversation.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the MCP server">
        Run this command in your terminal.

        ```bash theme={null}
        claude mcp add --transport http --scope user mapsdata https://www.mapsdata.io/mcp
        ```
      </Step>

      <Step title="Authenticate">
        Start Claude Code, enter `/mcp`, select **mapsdata**, and choose **Authenticate**. Sign in to Mapsdata in the browser and allow access.
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Add the server configuration">
        Open **Customize** in Cursor, click **MCPs**, then click **New MCP Server** and merge this entry into `mcp.json`.

        ```json theme={null}
        {
          "mcpServers": {
            "mapsdata": {
              "type": "http",
              "url": "https://www.mapsdata.io/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Sign in">
        Save the file, enable Mapsdata, and choose **Authenticate** if prompted. Complete the Mapsdata sign-in in your browser and click **Allow access**.
      </Step>

      <Step title="Verify the tools">
        Confirm that Mapsdata shows as connected and its tools are listed. Restart Cursor if the tool list does not refresh.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Codex">
    <Steps>
      <Step title="Add the MCP server">
        Run this command. Codex will register an OAuth client for Mapsdata.

        ```bash theme={null}
        codex mcp add mapsdata --url https://www.mapsdata.io/mcp --oauth-client-registration dcr
        ```
      </Step>

      <Step title="Sign in">
        Run the command below, sign in to Mapsdata in the browser, and click **Allow access**.

        ```bash theme={null}
        codex mcp login mapsdata --oauth-client-registration dcr
        ```
      </Step>

      <Step title="Verify the connection">
        Run `codex mcp list` and confirm that **mapsdata** is enabled with OAuth authentication.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Antigravity">
    <Steps>
      <Step title="Open the MCP configuration">
        Go to **Customizations → Installed**, scroll to **MCP Servers**, and click **Copy config file path**. Open that file.
      </Step>

      <Step title="Add Mapsdata">
        Merge this entry into the existing configuration and save it.

        ```json theme={null}
        {
          "mcpServers": {
            "mapsdata": {
              "serverUrl": "https://www.mapsdata.io/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="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.
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

<Steps>
  <Step title="Check the account">
    Call `check_account`. Do not request more than both `credits_remaining` and `max_results_per_search`.
  </Step>

  <Step title="Resolve the location">
    Call `find_locations` and select one returned location. Copy its `label` and `country_code` into `search_businesses`.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.