# Consultar CNPJ no Claude e em agentes de IA com o servidor MCP do apipj

> Servidor MCP do apipj: validar CNPJ, ver a base e consultar dados da Receita direto no Claude Code e em agentes de IA. Instalação testada.

Fonte: https://apipj.com.br/guias/consultar-cnpj-ia-mcp (atualizado em 13/10/2026)

O apipj tem um servidor MCP (Model Context Protocol) em `https://apipj.com.br/mcp`. Com ele, um agente de IA como o Claude Code consulta os dados cadastrais de um CNPJ, confere o dígito verificador e vê de que mês é a base, sem você escrever código de integração. Os dados são os mesmos da API: dados abertos da Receita Federal, carga de setembro de 2026.

## As três ferramentas

| Ferramenta | O que faz | Precisa da conta? |
|---|---|---|
| `validar_cnpj` | Confere formato e dígitos verificadores, inclusive do CNPJ alfanumérico. Igual a `GET /v1/valida/{cnpj}`. | Não, e não gasta cota |
| `status_base` | Mostra o mês da carga e o total de CNPJs na base. Igual a `GET /v1/status`. | Não |
| `consultar_cnpj` | Devolve o documento do CNPJ, no formato `completo` (padrão) ou `simplificado`. Igual a `GET /v1/cnpj/{cnpj}`. | Sim: login no Claude ou chave de API |

As três são só de leitura. `consultar_cnpj` usa a cota e o limite por minuto da sua conta, somados às chamadas que você faz pela API: no plano gratuito, 10 por minuto e 50.000 por mês.

## Usar no Claude (claude.ai, Desktop e celular)

Em **Personalizar > Conectores**, escolha **Adicionar conector personalizado** e informe a URL `https://apipj.com.br/mcp`. `validar_cnpj` e `status_base` já funcionam. Na primeira consulta de CNPJ, o Claude mostra o botão **Conectar**: ele abre a página da apipj, onde você entra com **Continuar com o Google** (sem conta, ela é criada na hora, grátis) ou com e-mail e senha e clica em **Autorizar**. Não há chave para copiar, e a consulta continua sozinha depois do login. O conector aparece no [painel](https://apipj.com.br/painel), em **Aplicativos conectados**, onde dá para desconectar.

## Instalar no Claude Code

O jeito mais curto é registrar o servidor sem cabeçalho: na primeira consulta (ou com `/mcp` numa sessão interativa), o Claude Code abre o navegador no mesmo login da apipj.

```bash
claude mcp add --transport http apipj https://apipj.com.br/mcp
```

Se preferir a chave de API (por exemplo, numa máquina sem navegador):

1. [Crie uma conta grátis](https://apipj.com.br/criar-conta) e copie a chave (`apipj_live_...`).
2. Deixe a chave numa variável de ambiente e registre o servidor:

```bash
export APIPJ_KEY="apipj_live_sua_chave"
claude mcp add --transport http apipj https://apipj.com.br/mcp --header "Authorization: Bearer $APIPJ_KEY"
claude mcp list
```

O último comando deve mostrar `apipj: https://apipj.com.br/mcp (HTTP) - ✔ Connected`. A partir daí, peça em linguagem natural, por exemplo: "consulte o CNPJ 00.000.000/0001-91 e me diga a situação cadastral e o município".

## Outros clientes MCP

Clientes que seguem a autorização OAuth do MCP descobrem o login sozinhos: aponte para `https://apipj.com.br/mcp` e, na primeira consulta, eles abrem a mesma página de autorização. Os demais funcionam se permitirem definir um cabeçalho: envie `Authorization: Bearer <sua chave>`. O servidor não guarda sessão: cada requisição é independente.

Clientes sem OAuth e sem cabeçalho personalizado conseguem usar só `validar_cnpj` e `status_base`.

## Testar sem cliente MCP

Para conferir que o servidor responde, chame a ferramenta aberta com curl:

```bash
curl -s https://apipj.com.br/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"validar_cnpj","arguments":{"cnpj":"12.ABC.345/01DE-35"}}}'
```

A resposta traz `"valido":true`, `"alfanumerico":true` e `"formatado":"12.ABC.345/01DE-35"`. Para `consultar_cnpj`, acrescente o cabeçalho `Authorization: Bearer $APIPJ_KEY`.

## O que o agente recebe quando algo dá errado

Sem conta conectada, `consultar_cnpj` recebe HTTP 401 com o pedido de login: no Claude, aparece o botão **Conectar**; clientes sem OAuth recebem uma frase explicando como informar a chave. Os demais erros voltam como resultado da ferramenta (`isError: true`) com uma frase que o próprio agente consegue repassar:

| Situação | O que acontece |
|---|---|
| Chave inválida ou CNPJ com dígito errado | Explica o problema; nada é cobrado da cota |
| CNPJ fora da base | Avisa que o CNPJ não foi encontrado na carga atual |
| Limite por minuto | Informa quantos segundos esperar |
| Cota do mês esgotada | Informa a data de renovação e o link de [preços](https://apipj.com.br/precos) |

`validar_cnpj` com um número inválido não é erro: a resposta vem normal, com `"valido":false` e o motivo.

## Precisa de mais consultas por minuto?

O limite por minuto e a cota do mês são os do plano da sua conta, e valem para o MCP e para a API juntos. Se o agente começar a receber "limite por minuto" com frequência, ou se a cota acabar antes do fim do mês, o caminho é trocar de plano. O checkout abre direto, e a mesma conta (com o login no Claude ou com a chave) passa a ter o limite novo assim que o pagamento é confirmado:

| Plano | Consultas por minuto | Consultas por mês | Preço | Assinar |
|---|---|---|---|---|
| Gratuito | 10 | 50.000 | grátis | [criar conta](https://apipj.com.br/criar-conta) |
| Dev | 30 | 200.000 | R$ 12,90/mês | [assinar o Dev](https://apipj.com.br/painel?assinar=dev) |
| Pro | 200 | 600.000 | R$ 59,90/mês | [assinar o Pro](https://apipj.com.br/painel?assinar=pro) |

Se você ainda não estiver logado, o link pede o login e volta direto para o pagamento. Detalhes em [preços](https://apipj.com.br/precos).

## Limites e cuidados

- **Ritmo:** além do limite do seu plano, o servidor aceita até 120 requisições por minuto por IP sem credencial e 3.000 com credencial.
- **Dados de sócios:** o formato completo traz o quadro societário exatamente como a Receita publica, com CPF mascarado. Quando o agente estiver só conferindo situação ou endereço, prefira o formato `simplificado` e não peça mais dados do que precisa. Veja a [política de privacidade](https://apipj.com.br/privacidade).
- **Frescor:** a base é mensal. Para prova oficial da situação de uma empresa, vale o comprovante emitido no site da Receita.

## Próximos passos

- [Documentação da API](https://apipj.com.br/docs): os mesmos dados por HTTP, com todos os campos.
- [OpenAPI pública](https://apipj.com.br/openapi-publica.json): especificação para geradores de cliente e agentes que leem OpenAPI.
- [Validar fornecedor pelo CNPJ](https://apipj.com.br/guias/validar-fornecedor-cnpj): um bom roteiro para pedir ao agente.