---
title: "API de CNPJ para agentes"
description: "Conecte Claude, Cursor, Windsurf ou um agente OpenAI à base de empresas do Brasil pelo MCP oficial: consultar, buscar, gerar filtro e ver uso."
canonical: "https://cnpj.ia.br/api-cnpj-para-agentes"
date_modified: 2026-09-03
source: "cnpj.ia.br"
---

para quem constrói agentes · base agosto/2026

# API de CNPJ para agentes

Conecte Claude, Cursor, Windsurf ou um agente OpenAI à base de empresas do Brasil pelo MCP oficial: consultar, buscar, gerar filtro e ver uso.

[Conectar o MCP](https://cnpj.ia.br/docs/mcp) [Criar chave grátis](https://app.cnpj.ia.br/signup)

Um agente que precisa saber se uma empresa existe, o que ela faz, onde está e como contatá-la resolve isso com quatro ferramentas MCP sobre a base da Receita Federal de agosto/2026: `consultar_cnpj`, `buscar_empresas`, `gerar_filtro` e `ver_uso`. A chave é a mesma da API REST, o custo em créditos é o mesmo, e consulta, busca e filtro trazem a data da base em `meta.data_as_of`.

## O fluxo em três passos

1. Crie a chave e cole no cliente

   Uma chave da conta, no header Authorization. Claude Code, Cursor e Windsurf conectam direto ao servidor remoto; Claude Desktop pela ponte mcp-remote.

   ```
   claude mcp add --transport http cnpjia https://mcp.cnpj.ia.br \
     --header "Authorization: Bearer $CNPJIA_KEY"
   ```

2. Deixe o agente perguntar em português

   gerar_filtro transforma a pergunta em filtros da busca; buscar_empresas pagina por cursor; consultar_cnpj traz o cadastro ou o perfil completo.

   ```
   "Liste padarias ativas em Curitiba optantes do Simples e me diga quantas são."
   ```

3. Controle o gasto pelo próprio agente

   ver_uso devolve franquia, consumo e reset. A chave fica no cliente; o agente não compra créditos nem muda de plano.

   ```
   ver_uso → credits_remaining, cycle_reset_at, rpm
   ```

## Código pronto

O servidor é remoto e fala HTTP. A configuração muda por cliente; a chave fica sempre do lado do agente.

#### Claude Code

```bash
claude mcp add --transport http cnpjia https://mcp.cnpj.ia.br \
  --header "Authorization: Bearer $CNPJIA_KEY"
```

#### Cursor

```json
{
  "mcpServers": {
    "cnpjia": {
      "url": "https://mcp.cnpj.ia.br",
      "headers": { "Authorization": "Bearer cnpj_live_..." }
    }
  }
}
```

#### OpenAI

```python
import os
from openai import OpenAI

client = OpenAI()
resp = client.responses.create(
    model="gpt-5",
    tools=[{
        "type": "mcp",
        "server_label": "cnpjia",
        "server_url": "https://mcp.cnpj.ia.br",
        "headers": {"Authorization": f"Bearer {os.environ['CNPJIA_KEY']}"},
        "require_approval": "never",
    }],
    input="Quantas empresas de software ativas existem em Florianópolis?",
)
print(resp.output_text)
```

Claude Desktop não aceita servidor remoto com header no arquivo local de configuração; a ponte `mcp-remote` resolve. Windsurf usa `serverUrl` no lugar de `url`. Os quatro casos estão em [Servidor MCP](https://cnpj.ia.br/docs/mcp).

## O que o agente passa a responder

- “Qual é a situação cadastral e o CNAE principal do CNPJ 00.000.000/0001-91?” → `consultar_cnpj` em `basic`.
- “Me dá o telefone e os sócios do Banco do Brasil.” → `consultar_cnpj` em `full`.
- “Quantas empresas de software ativas existem em Florianópolis?” → `gerar_filtro` e depois `buscar_empresas`; a primeira página já traz a contagem com teto em `meta.total_count_capped`.
- “Quantos créditos ainda tenho este mês?” → `ver_uso`.

O agente decide o perfil a partir do pedido. Se quiser economizar, oriente no prompt do sistema a usar `basic` e só pedir `full` quando `has_phone` ou `has_email` vierem verdadeiros.

## Campos mais usados

| Campo | Perfil | Descrição |
| --- | --- | --- |
| [`razao_social`](https://cnpj.ia.br/docs/campos#campo-razao_social) | basic | Nome empresarial registrado na Receita Federal. É o único nome sempre presente. |
| [`situacao_cadastral.descricao`](https://cnpj.ia.br/docs/campos#campo-situacao_cadastral.descricao) | basic | Descrição da situação cadastral, traduzida do código pela tabela de domínio da Receita Federal. |
| [`cnae_fiscal.descricao`](https://cnpj.ia.br/docs/campos#campo-cnae_fiscal.descricao) | basic | Nome da atividade econômica principal, traduzido do código pela tabela de CNAEs da Receita Federal. |
| [`endereco.uf`](https://cnpj.ia.br/docs/campos#campo-endereco.uf) | basic | Sigla da unidade da federação do estabelecimento, campo da Receita Federal. |
| [`has_phone`](https://cnpj.ia.br/docs/campos#campo-has_phone) | basic | Indica se a empresa tem pelo menos um telefone na base. Sinal derivado, calculado no processamento da Oportunidados. |
| [`telefones[].numero`](https://cnpj.ia.br/docs/campos#campo-telefones[].numero) | full | Número do telefone, sem DDD e sem pontuação, cadastrado na Receita Federal. |
| [`email`](https://cnpj.ia.br/docs/campos#campo-email) | full | Endereço de correio eletrônico do contribuinte, campo da Receita Federal. `null` quando a empresa não tem e-mail na base. |
| [`meta.total_count_capped`](https://cnpj.ia.br/docs/campos#campo-meta.total_count_capped) | meta | Contagem total da coorte com teto de exibição, em texto (por exemplo `10000+`). Tem cache de 1 hora. |

## Limites que o agente precisa respeitar

- O limite de requisições por minuto é da conta, somando agente e API REST. Um agente em loop chega a `rate_limited`; a resposta traz `Retry-After` e o agente deve esperar.
- `buscar_empresas` está nos planos pagos. No Free a ferramenta aparece em `tools/list`, mas responde `insufficient_plan` com um link para os planos, sem consumir crédito.
- Chave revogada é recusada pela API na próxima chamada e pelo MCP em até 60 segundos.

## Tier indicado

**Starter** é o plano indicado: o de menor mensalidade entre os que incluem a busca de empresas.

O Free não atende a este fluxo porque não inclui a busca de empresas.

- 15 mil créditos por mês
- 30 requisições por minuto
- R$ 0,0196 por consulta `full`
- R$ 0,0033 por empresa retornada na busca

[Todos os planos, os pesos por operação e os pacotes avulsos](https://cnpj.ia.br/precos)

## Perguntas frequentes

**Preciso de OAuth para conectar o agente?**

Não. O servidor aceita a chave da conta no header `Authorization: Bearer`, a mesma da API REST. Não há fluxo OAuth nem token separado para o MCP.

**Funciona com Claude Desktop, Cursor, Windsurf e agentes OpenAI?**

Claude Code, Cursor e Windsurf conectam direto ao servidor remoto. Claude Desktop precisa da ponte `mcp-remote`, porque o arquivo local de configuração só aceita servidores locais. Agentes construídos com a Responses API da OpenAI usam a ferramenta `mcp` com `server_url` e `headers`.

**O agente pode comprar créditos ou mudar meu plano?**

Não. As ferramentas são consulta, busca, geração de filtro e leitura de uso. Compra de pacote e troca de plano acontecem no portal, por uma pessoa autenticada.

**Quanto custa uma pergunta do agente?**

O mesmo que a chamada HTTP equivalente: consultar em `basic` ou `full`, buscar por empresa retornada, gerar filtro por chamada, ver uso sem custo. Os pesos estão em `/precos` e o agente vê o saldo com `ver_uso`.

**A busca funciona no plano Free?**

Não. `buscar_empresas` está nos planos pagos; no Free ela responde `insufficient_plan` com um link para os planos, sem consumir crédito. Consulta, geração de filtro e uso funcionam no Free.

**Os dados que o agente recebe são atuais?**

São a foto mensal dos dados abertos da Receita Federal, com a data em `meta.data_as_of` de toda resposta de consulta e busca. Uma alteração cadastral feita hoje aparece na próxima carga mensal; o agente pode informar a data ao usuário.

## Para continuar

- [Servidor MCP](https://cnpj.ia.br/docs/mcp)
- [Busca de empresas](https://cnpj.ia.br/docs/busca-empresas)
- [cnpj.ia.br vs BrasilAPI: qual escolher?](https://cnpj.ia.br/comparar/brasilapi)

[Conectar o MCP](https://cnpj.ia.br/docs/mcp)