A API v4 expõe um servidor MCP embutido. Aponte o Claude ou o ChatGPT para um endpoint, autorize com o seu login — sem colar chave — e ganhe 16 tools de busca, segmentação, decisores e grupo econômico, com leitura de prospecção em cima do dado.
claude mcp add --transport http --scope user econodata-v4 \ https://api.econodata.com.br/v4/mcp # na 1ª chamada o navegador abre para você autorizar # → econodata-v4 connected (16 tools)
A API v4 expõe um servidor MCP (Model Context Protocol) em POST /v4/mcp — Streamable HTTP, stateless. O agente conecta com o login da pessoa (OAuth 2.1 com PKCE) e reusa os mesmos endpoints e billing da API.
Busca, match, segmentação, organograma, grupo econômico, tags e saldo — as mesmas capacidades da API, expostas como tools para o agente, mais o ajuste do nível de inteligência.
Nada de chave colada em arquivo: você informa o endereço, entra com o seu login da plataforma e autoriza numa tela que mostra qual IA está pedindo, qual conta será usada e o que ela poderá fazer. Testado em Claude (web, desktop e Code), ChatGPT e Gemini Enterprise.
Cada tool exige o escopo da sua capacidade e cobra tokens da mesma conta da API. Privilégio mínimo por padrão, e o agente não enxerga tool que não pode chamar.
A liberação é feita pelo time da Econodata na sua conta. Contas em trial não têm acesso ao MCP — se você está avaliando a plataforma, fale com o time comercial para habilitar. Confirme a liberação no menu Integrações & API v4 da plataforma: se ele aparece, sua conta está liberada.
O que cada plano permite é limitação da IA, não nossa — e varia bastante: no Claude o plano gratuito já conecta, no ChatGPT não. Confira o quadro por IA abaixo antes de tentar.
As tools de dados cobram tokens da sua conta; sem saldo elas retornam 402. Peça o saldo ao agente a qualquer momento (“quanto de saldo eu tenho?”) — essa consulta é grátis.
Em todas elas o endereço é o mesmo — https://api.econodata.com.br/v4/mcp — e a autorização é feita com o seu login da plataforma. Não existe chave para colar.
| Assistente | Plano mínimo para conectar | Detalhe importante |
|---|---|---|
| Claude (web e desktop) | Gratuito já conecta | O plano gratuito permite 1 conector personalizado no total. Em contas Team/Enterprise, só o proprietário adiciona o conector; depois cada pessoa autoriza a sua. |
| Claude Code (terminal) | Segue o seu plano do Claude | — |
| ChatGPT | Plus, Pro, Business, Enterprise ou Edu | Não funciona no gratuito — o Developer mode, onde ficam os conectores personalizados, não existe lá. |
| Gemini Enterprise | Licença Gemini Enterprise | Conecta. Exige credenciais dedicadas que emitimos para a sua organização. |
| Gemini — uso individual | não se aplica | Não há onde configurar um servidor MCP no app de pessoa física. Não é restrição nossa: essa tela não existe no produto. |
No Claude, vá em Configurações → Conectores e clique em Adicionar conector personalizado.
Nome: Econodata · URL do servidor MCP: https://api.econodata.com.br/v4/mcp. Se a tela oferecer client ID e client secret, deixe em branco — são opcionais e o nosso servidor se registra sozinho.
Clique em Adicionar. O Claude mostra o conector com um botão Conectar — clique nele. Abre a página da Econodata; faça login se pedir.
A tela mostra qual IA está pedindo acesso, qual conta Econodata será usada e o que ela poderá fazer. Clique em Autorizar e volte ao Claude: o conector aparece com um ✓.
claude mcp add --transport http --scope user econodata-v4 \ https://api.econodata.com.br/v4/mcp
No ChatGPT, vá em Configurações → Conectores (ou Apps, conforme a versão). Desça até Configurações avançadas e ative o Developer mode — é ele que libera conector personalizado. Volte a Conectores e clique em Criar.
Nome: Econodata · Descrição: Dados de empresas brasileiras para prospecção · URL do servidor MCP: https://api.econodata.com.br/v4/mcp · Autenticação: OAuth.
Salve e clique em Conectar. Abre a tela da Econodata: entre com o seu login da plataforma, confirme a conta e clique em Autorizar.
Na conversa, abra o menu de ferramentas e marque o conector Econodata. A partir daí o ChatGPT usa as tools quando o assunto for empresa, mercado ou prospecção.
Ao autorizar, a Econodata cria sozinha uma credencial para aquela IA e a amarra à sua conta e ao seu login. É ela que carrega os escopos — a lista do que o agente pode fazer. Cada tool exige o seu escopo; o agente só vê as tools que a sua conta alcança.
A credencial da IA aparece no seu painel. Em Integrações & API v4 você vê uma linha por IA conectada, identificada pelo nome da IA e pelo e-mail do login que autorizou — por exemplo Claude — usuário maria@empresa.com.br. É por ali que você revoga o acesso de uma IA sem afetar as outras. Contas em trial não alcançam o MCP; a liberação é feita pelo time da Econodata.
O MCP não devolve só a tabela. Junto do dado vai uma leitura de prospecção — quem procurar primeiro, por qual porta entrar, o que o número sugere. Você escolhe a profundidade dessa leitura, e a escolha fica salva para aquele assistente.
| Nível | O que você recebe | Quando escolher |
|---|---|---|
baixo |
Só o dado da Econodata, sem interpretação. Nada é acrescentado por fora da nossa base. | Quando você vai tratar os dados por conta própria, ou precisa de saída limpa para planilha e sistema. |
medio padrão |
O dado com leitura comercial e complementos do que a IA sabe — nos mesmos tipos de informação que a Econodata cobre. Se a empresa não tem site na nossa base e a IA conhece, ela completa — e identifica que aquilo é complemento, não medição nossa. | O uso do dia a dia: qualificar uma conta, entender um recorte, priorizar uma lista. |
alto |
Tudo do médio, e a IA busca ativamente notícias, pesquisas e sinais de mercado, cruza com o nosso dado, hierarquiza alvos, aponta timing e monta hipótese com contraponto. | Preparar uma abordagem de peso, montar tese de território, entrar em reunião com contexto. |
Como trocar: peça na conversa — “mude o nível de inteligência para alto”. O agente só troca quando o pedido é explícito sobre o nível: dizer “seja mais direto” ou “resuma isso” muda o tom da resposta, não a configuração. A escolha fica salva para aquele assistente e vale nas conversas seguintes — se você usa Claude e ChatGPT, cada um tem o seu nível. Para saber onde está, pergunte “qual o meu nível de inteligência?”.
O dado medido sempre prevalece. Em qualquer nível, se o que a IA “sabe” contradiz o que a Econodata mediu, vale o nosso dado e a divergência é apontada. E a IA não pode afirmar faturamento, número de funcionários, porte ou contagem que não tenha vindo de uma consulta — é neles que você decide, então eles não podem ser estimados por fora.
Além das tools, o servidor entrega quatro roteiros que a sua IA pode oferecer pelo nome — no Claude eles aparecem no menu do conector. Cada um já sabe a sequência de consultas e a leitura que faz sentido no fim.
Cada tool reusa os endpoints e o billing da API. Tools de dados cobram tokens; saldo, tags e nível de inteligência são grátis. Você não chama tool na mão — pergunta em linguagem natural e o agente escolhe.
| Tool | O que faz | Escopo | Cobrança |
|---|---|---|---|
account_balance | Saldo de tokens da conta | account:read | grátis |
companies_search | Lookup de 1 empresa por cnpj, raizCnpj, site ou e-mail. O identificador muda a base cobrada: resolver por site/e-mail custa mais que por CNPJ. | companies:read | base + campos |
companies_lookup_batch | Lookup em lote (1–100 CNPJs) | companies:read | base/empresa + campos |
companies_match | Match por nome+uf ou identificador exato → top-N | companies:match | base + candidatos |
companies_search_list | Segmentação paginada por filtros | companies:search_list | base + campos/empresa |
companies_search_list_by_id | Segmentação por pesquisa salva (nome exato) | companies:search_list_by_id | idem search_list |
companies_calc_list | Só a contagem por filtros | companies:search_list | só base |
companies_calc_list_by_id | Só a contagem por pesquisa salva | companies:search_list_by_id | só base |
companies_saved_searches | Lista as pesquisas salvas compartilhadas da conta (o nome a usar nas duas tools acima) | companies:search_list_by_id | grátis |
company_people | Organograma (decisores/colaboradores) paginado | companies:people | base + por pessoa |
economic_group | Empresas ligadas por sócios (experimental) | companies:economic_group | base + por empresa |
companies_tag | Adiciona tags a empresas | tags:write | grátis |
companies_untag | Remove tags | tags:write | grátis |
tag_job_status | Status de job assíncrono de tags | tags:read | grátis |
nivel_inteligencia | Mostra o nível de inteligência configurado para a conta | account:read | grátis |
configurar_inteligencia | Troca o nível de inteligência — só quando você pede explicitamente | account:read | grátis |
Dry-run: sete tools aceitam estimar: true → devolvem só { tokensEstimados } sem debitar nem entregar dado, para o agente orçar antes: companies_search, companies_lookup_batch, companies_match, companies_search_list, companies_search_list_by_id, company_people e economic_group. As duas de contagem não aceitam o parâmetro — em companies_calc_list e companies_calc_list_by_id a contagem roda e debita, mesmo que o agente mande estimar.
O custo é a base do endpoint mais os campos entregues por empresa. Consultas repetidas não recobram dentro da janela de dedup.
Custo = base do endpoint + Σ campos entregues por empresa (por classe de valor). Re-puxar a mesma empresa em 24h não recobra (dedup por (empresa, bucket)); pedir mais campos cobra só o diff.
Sem saldo, nada é entregue e a tool retorna 402. Cheque antes com account_balance ou com estimar: true para orçar a chamada.
60 req/min por credencial (rajada 120) + teto por conta (5×). Estouro retorna 429.
O agente traduz a intenção do usuário para a tool certa. Alguns exemplos:
O que pode dar errado e o que cada caso significa. Atenção ao formato: só 401 e 429 chegam como status HTTP, porque são barrados antes do MCP. Os demais voltam dentro de uma resposta 200 como erro da tool, com a mensagem em português — é esse texto que o agente mostra, não o número.
A autorização expirou ou foi revogada — reconecte a IA e autorize de novo. Chega como status HTTP.
A sua conta não alcança a capacidade que a tool exige. Chega como erro da tool, com o que falta no texto: Credencial de API sem escopo para esta tool: requer 'tags:write'
O saldo de tokens da conta é insuficiente para a chamada. Chega como erro da tool.
A empresa, a pesquisa salva ou o job informado não existe. Chega como erro da tool.
Algum argumento é inválido — CNPJ com número de dígitos diferente de 14, filtro ou enum fora do contrato. Chega como erro da tool.
O rate-limit foi excedido: 60 req/min por credencial, rajada de 120 e teto por conta de 5×. Chega como status HTTP.
Um datastore (Elasticsearch ou Postgres) está indisponível. É falha de infraestrutura, não da chamada.
Cada IA conectada tem a sua própria credencial, amarrada ao seu login. Você vê e corta cada uma delas sozinho, sem abrir chamado.
A IA nunca recebe o seu login nem sua senha. O que ela guarda é uma autorização revogável, limitada ao que a tela de consentimento mostrou.
Em Integrações & API v4, encontre a linha da IA — identificada pelo nome dela e pelo e-mail de quem autorizou — e revogue. Aquela IA perde o acesso na hora; as outras seguem funcionando.
Buscas debitam tokens da conta e marcar empresas com tag escreve na base que o seu time usa no dia a dia. O agente pode estimar o custo antes de consultar — basta pedir a estimativa.
Dê ao seu agente de IA acesso a dados de milhões de empresas brasileiras — buscas, decisores e grupos econômicos em linguagem natural, sem sair da conversa. Fale com nosso time e veja na prática.
API v4