Esta página aún no está traducida. Estás leyendo la versión en inglés.

Connect MapDove to AI assistants

Use MapDove's foot-traffic, trade-area and site-selection tools from Claude, ChatGPT, Groq, Cursor, VS Code and other MCP clients through the hosted MCP server.

MapDove runs a hosted MCP server (Model Context Protocol), so AI assistants can look up places, brands and markets and run your site analyses while they answer. You ask in plain language and the assistant calls MapDove’s tools for you, as you, with your plan’s limits.

Server URL https://api.mapdove.com/mcp
Sign-in your MapDove account (OAuth), or an API key for clients that send a header
Plans every plan, Free included, when you sign in with your account. API keys need a plan with API access (Pro and above)

Your data is never public. Each person connects with their own MapDove account and sees what their workspace’s plan allows. The assistant can read MapDove data and run analyses, but it can’t change anything: no edits to projects, alerts, members or billing.

What the assistant can do

The server offers the same 24 read-only tools as MapDove’s in-app assistant, plus search and fetch:

  • Look things up: list_cities, list_categories, list_brands, search_places, search (places, brands, cities and categories by name) and fetch (one of them by id).
  • Places: place_detail, place_visits, place_trade_area, place_nearby, cross_shopping, place_workforce, place_seasonality.
  • Markets and brands: rankings, market_overview, brand_performance, market_share, market_seasonality, market_migration.
  • Site analyses (each uses one analysis of your plan’s monthly allowance): site_suitability, score_sites, huff_forecast, catchment, workforce_area, area_analysis, tenant_gaps.

Visit figures are modeled estimates, not measurements. Place data in the hosted product is © OpenStreetMap contributors and, in the US, © Overture Maps Foundation; ask the assistant to keep those credits when it shows places. Workforce figures come from US Census LEHD LODES and county migration from the US Census ACS county-to-county flows (2016–2020) where available; both are measured estimates, and migration figures come with their margins of error.

Try questions like:

  • “Which coffee brands gained the most market share in Austin over the last 90 days?”
  • “Score these two corners for a new gym and compare their catchments.”
  • “What brands are missing around our store on South Lamar in Austin? Run a tenant gap report.”

Claude

Works in Claude on the web, Claude Desktop and the mobile apps, on every Claude plan that supports custom connectors.

  1. In Claude, open Customize → Connectors (on Team and Enterprise plans an owner adds it under Organization settings → Connectors).
  2. Click + Add, then Add custom connector.
  3. Enter the name MapDove and the URL https://api.mapdove.com/mcp. Leave the OAuth client fields empty: Claude registers itself.
  4. Click Add, then Connect. A MapDove window opens: sign in if you aren’t already, check the details and click Approve.
  5. In a chat, enable MapDove from the tools menu and ask your question.

Claude Code (the terminal app) connects the same way: claude mcp add --transport http mapdove https://api.mapdove.com/mcp, then run /mcp to sign in.

ChatGPT

ChatGPT adds custom MCP servers on the web. Availability depends on your ChatGPT plan and your workspace admin’s settings.

  1. Go to chatgpt.com/plugins (on older menus: Settings → Apps & Connectors → Developer mode).
  2. Click +, then Add custom MCP server.
  3. Enter the name MapDove, an optional description, and the server URL https://api.mapdove.com/mcp.
  4. Under Authentication, choose OAuth. ChatGPT registers itself; no client ID is needed.
  5. Confirm, install it, and approve the connection on the MapDove page that opens.
  6. In a chat, mention MapDove (type @) and ask your question. MapDove’s tools are marked read-only, so ChatGPT doesn’t ask you to confirm each call.

MapDove’s search and fetch tools follow the shapes ChatGPT expects for deep research, so you can also select MapDove as a source there. ChatGPT doesn’t support API keys for custom servers: use OAuth.

Groq API

Groq calls remote MCP servers from its OpenAI-compatible Responses API. Send your MapDove API key as a header (create one in Settings → API keys; it needs a plan with API access). Remote MCP works with models such as openai/gpt-oss-120b, openai/gpt-oss-20b, llama-3.3-70b-versatile and llama-3.1-8b-instant; check Groq’s documentation for the current list.

curl https://api.groq.com/openai/v1/responses \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-oss-120b",
    "input": "What are the five busiest coffee shops in Austin, with their modeled visits?",
    "tools": [{
      "type": "mcp",
      "server_label": "mapdove",
      "server_url": "https://api.mapdove.com/mcp",
      "headers": { "Authorization": "Bearer '"$MAPDOVE_API_KEY"'" },
      "require_approval": "never"
    }]
  }'
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["GROQ_API_KEY"], base_url="https://api.groq.com/openai/v1")

response = client.responses.create(
    model="openai/gpt-oss-120b",
    input="What are the five busiest coffee shops in Austin, with their modeled visits?",
    tools=[{
        "type": "mcp",
        "server_label": "mapdove",
        "server_url": "https://api.mapdove.com/mcp",
        "headers": {"Authorization": f"Bearer {os.environ['MAPDOVE_API_KEY']}"},
        "require_approval": "never",
        # Optional: limit the tools the model may call.
        # "allowed_tools": ["list_cities", "list_categories", "rankings", "place_detail"],
    }],
)
print(response.output_text)

Keep the API key on your server; never put it in a browser or a mobile app.

Cursor and VS Code

Both sign in with your MapDove account (OAuth) when you add the server without a key, or can send an API key header.

Cursor: add this to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "mapdove": { "url": "https://api.mapdove.com/mcp" }
  }
}

To use an API key instead, add "headers": { "Authorization": "Bearer ${env:MAPDOVE_API_KEY}" } next to url.

VS Code: add this to .vscode/mcp.json, or run MCP: Add Server from the Command Palette and choose HTTP:

{
  "servers": {
    "mapdove": { "type": "http", "url": "https://api.mapdove.com/mcp" }
  }
}

For an API key, add "headers": { "Authorization": "Bearer ${input:mapdove-key}" } and an inputs entry { "id": "mapdove-key", "type": "promptString", "password": true }.

Local alternative

The open-source @mapspot/mcp package runs a small MCP server on your own computer over stdio, with an API key. The hosted server above is the recommended option: it needs no install, supports OAuth sign-in and always has the full tool list. See the package README if you need a local process.

Usage, limits and billing

  • Signed in with your account (OAuth): tool calls count like using the MapDove app. Site analyses use your workspace’s monthly analyses; browsing places and markets is free. API calls are not counted.
  • With an API key: each tool call counts as one API call, like the REST API, and site analyses also use one analysis. Connecting and listing tools is free. Plans without API access get 402.
  • Every connection may make up to 60 tool calls per minute. Past that, the tool answers with a “rate limit” error and the assistant can try again a minute later.
  • Your plan’s history window applies: Free shows the last 90 days.

Manage and revoke access

  • Settings → Connected apps lists the assistants you connected, when, and when they last used MapDove. Disconnect stops one immediately.
  • Settings → Organization → AI connectors: workspace owners and admins can turn off all third-party AI assistants for the workspace. Connected assistants and API-key MCP clients stop working right away; turning it back on restores them.
  • Revoking an API key, removing a member or suspending an account also ends their access.
  • MapDove records approvals, disconnections and suspicious token reuse in the workspace’s audit log (Settings → Audit log).

Privacy

When you connect an AI assistant, the questions you ask stay with that assistant’s provider (for example Anthropic for Claude or OpenAI for ChatGPT). MapDove only receives the tool calls the assistant makes and returns the data they ask for, which the provider then processes under your own agreement with it. MapDove stores the connection (which app, for which account and workspace), hashed tokens and audit entries; it doesn’t store your chats. See the Privacy Policy.

For developers

  • Transport: MCP Streamable HTTP, POST https://api.mapdove.com/mcp, JSON responses. Protocol revisions 2026-07-28 (stateless) and 2025-11-25, 2025-06-18 and 2025-03-26 (with initialize and Mcp-Session-Id).
  • OAuth 2.1 with PKCE (S256), dynamic client registration, and resource indicators. Discovery: https://api.mapdove.com/.well-known/oauth-protected-resource/mcp and https://api.mapdove.com/.well-known/oauth-authorization-server. The single scope is mcp.
  • Redirect URIs must be https, or http on localhost / 127.0.0.1 / [::1] for desktop apps, and match exactly.
  • The full contract is in the API reference (“Remote MCP server”).