MapsData

npx add-mcp 'https://mapsdata.ai/mcp'

Conecte um agente de IA

MapsData é um servidor MCP remoto, então um assistente de IA pode montar suas listas de leads diretamente. Conecte-o uma vez e você pode pedir ao Claude ou a outro agente para encontrar encanadores no Texas, e ele verificará a categoria, iniciará a coleta e entregará o arquivo quando terminar.

MCP é o Model Context Protocol, um padrão aberto para dar a um assistente acesso a uma ferramenta. Nosso servidor está em:

https://mapsdata.ai/mcp

Incluído em todos os planos pagos, assim como a API REST, e usa as mesmas chaves de API. Coletas iniciadas por um agente contam contra a mesma cota mensal que todo o resto.

Conectando

A autenticação é um token bearer: sua chave de API do MapsData, criada em Configurações. Veja autenticação para saber como as chaves funcionam.

Claude Code

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

Cursor

Em ~/.cursor/mcp.json, ou no .cursor/mcp.json do projeto:

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

Qualquer outra ferramenta

Qualquer cliente que suporte MCP HTTP com streaming e permita definir um cabeçalho funcionará. O servidor não tem estado: ele não emite ID de sessão, e cada chamada é um único POST.

Conectores hospedados

Diretórios como o do Claude.ai não têm onde colocar um cabeçalho, então eles usam OAuth. O MapsData suporta isso: registro dinâmico de clientes, fluxo de código de autorização com PKCE e tokens de atualização rotativos. Aponte o conector para https://mapsdata.ai/mcp e ele descobrirá o resto, depois enviará você para uma tela de consentimento que nomeia o aplicativo e declara claramente que aprová-lo permite que esse aplicativo gaste sua cota mensal de leads.

Conexões aprovadas aparecem em Configurações ao lado de suas chaves de API, e desconectar uma tem efeito imediato.

Ferramentas

Ferramenta	O que faz
mapsdata_search_categories	Encontra a categoria exata do Google Maps para coletar
mapsdata_list_regions	Nomes de regiões válidos para um país
mapsdata_get_usage	Cota restante neste ciclo e a maior coleta que você pode iniciar agora
mapsdata_start_scrape	Inicia uma coleta. Suporta execução de teste.
mapsdata_get_scrape	Verifica uma coleta
mapsdata_list_scrapes	Coletas recentes, das mais novas para as mais antigas
mapsdata_get_download_link	Um link de 15 minutos para os resultados
mapsdata_cancel_scrape	Cancela uma coleta na fila ou em andamento

Cancelar está marcado como destrutivo, então um cliente bem-comportado pedirá sua confirmação antes de executar. Isso é proposital: cancelar uma coleta em andamento ainda cobra pelos leads já entregues.

Um exemplo prático

Peça o que você quer em linguagem simples:

Find me 500 plumbers in Texas with email addresses.

Um agente bem-comportado confirmará que a categoria é coletável, iniciará o trabalho e então parará em vez de ficar em um 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."

Depois, peça para ele verificar e buscar o arquivo:

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

Por que ele não fica em loop de consultas

Uma coleta leva de minutos a horas, o que é um formato desconfortável para um assistente. Cada resposta de trabalho traz um valor de poll_after_seconds e uma instrução explícita de next_action dizendo ao agente para reportar e parar. Agentes seguem um campo na resposta com muito mais confiabilidade do que seguem uma descrição, então ambos estão presentes.

Se um agente entrar em loop mesmo assim, os limites de taxa o impedem: 120 chamadas por minuto por chave, 300 por minuto em todo o seu workspace e 10 envios de coleta por minuto. Um limite de borda fica na frente de tudo isso.

Um agente também não pode estourar sua cota em uma única chamada. total_limit é limitado aos leads que você ainda tem neste ciclo, e mapsdata_get_usage reporta max_rows_this_scrape para que um agente bem-comportado dimensione a solicitação antes de fazê-la. Quando uma coleta é reduzida, a resposta diz isso e instrui o agente a repassar a informação.

Quando algo dá errado

Falhas de ferramenta retornam como erros legíveis que o agente pode tratar, em vez de falhas de protocolo, e elas nomeiam a ferramenta que resolve o problema. Pedir uma categoria que não existe instrui o agente a chamar mapsdata_search_categories; usar TX em vez de Texas instrui a chamar mapsdata_list_regions. Na prática, o agente se corrige e tenta novamente sem envolver você.

Segurança

• Sua chave é a cota do seu workspace. Um agente que a possua pode gastar a cota do mês. Use uma chave criada para isso, para que você possa revogá-la sem quebrar mais nada.
• Somente leitura, se preferir. Escolha "Somente leitura" ao criar a chave em Configurações, e o assistente poderá verificar e baixar coletas existentes, mas nunca iniciar ou cancelar uma.
• Cancelar custa dinheiro. Está marcado como destrutivo para que seu cliente peça confirmação primeiro. Mantenha essa confirmação ativada.