Servidor MCP do cnpj.ia.br

O servidor MCP em https://mcp.cnpj.ia.br expõe a API como ferramentas para agentes: o agente consulta uma empresa, busca empresas por filtro, transforma uma descrição em filtros e consulta o uso, com o mesmo custo em créditos da API REST, por login no claude.ai ou pela mesma chave. Na conexão por chave, ela fica guardada no cliente do agente e vai ao servidor só no header de cada chamada, para validação; o agente não compra créditos nem muda de plano.

Conectar

claude.ai (conector personalizado)

Use a URL https://mcp.cnpj.ia.br (a raiz, sem /mcp):

1. Adicione o conector com a URL.
2. Clique em Conectar.
3. Aprove o acesso na tela de autorização do servidor MCP do cnpj.ia.br e entre com a sua conta do portal (app.cnpj.ia.br).
4. O navegador volta ao claude.ai com o conector ativo.

Em planos Team e Enterprise, só Owner ou Primary Owner adiciona o conector, em Organization settings › Connectors. Depois cada membro abre Customize › Connectors, encontra o conector (rótulo “Custom”) e clica em Connect para autenticar com a própria conta. Em planos individuais, o próprio usuário adiciona em Customize › Connectors › Add custom connector.

Outros clientes (chave no header)

Transporte HTTP, autenticação pela chave da conta no header Authorization. Crie a chave em app.cnpj.ia.br e cole no cliente:

{
  "mcpServers": {
    "cnpjia": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.cnpj.ia.br",
               "--header", "Authorization: Bearer ${CNPJIA_KEY}"],
      "env": { "CNPJIA_KEY": "cnpj_live_..." }
    }
  }
}

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

# Codex lê a chave da variável de ambiente a cada início; ela não fica no config.toml
export CNPJIA_KEY="cnpj_live_..."
codex mcp add cnpjia --url https://mcp.cnpj.ia.br --bearer-token-env-var CNPJIA_KEY

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

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

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="Qual é a situação cadastral do CNPJ 00.000.000/0001-91?",
)
print(resp.output_text)

Os caminhos de arquivo variam por cliente (Claude Desktop: claude_desktop_config.json, que só aceita servidores locais e por isso usa a ponte mcp-remote; Cursor: .cursor/mcp.json; Windsurf: mcp_config.json). Com a conexão feita, tools/list devolve as quatro ferramentas abaixo e nada mais.

As quatro ferramentas

gerar_filtro recebe uma descrição em linguagem natural (“padarias ativas em Curitiba optantes do Simples”) e devolve os filtros estruturados que buscar_empresas aceita. É a ponte entre a pergunta do usuário e a busca, e custa 1 crédito por chamada, independentemente do resultado.

Exemplos de perguntas

• “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, CNPJ 00.000.000/0001-91.” → 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.
• “Quantos créditos ainda tenho este mês?” → ver_uso.

O agente decide o perfil a partir do pedido; oriente-o no prompt do sistema se quiser forçar basic para economizar.

Limites

• Requisições por minuto: as do plano da conta, contadas junto com as chamadas da API REST. Um agente em loop atinge rate_limited rápido; o servidor devolve o erro com Retry-After e o agente deve esperar.
• Free: 60 créditos por mês, sem buscar_empresas. A ferramenta aparece em tools/list, mas responde insufficient_plan com um link para /precos.
• Chave revogada: o servidor valida a chave com um cache de até 60 segundos; depois disso recusa a conexão.

Segurança

A chave fica no cliente do agente, em arquivo de configuração local ou em variável de ambiente, e chega ao servidor MCP no header de cada chamada, onde é validada contra a API. O servidor exige autenticação por login (OAuth) ou por chave, não guarda a chave e não tem operação de compra: crédito e plano se gerenciam no portal, por uma pessoa. Se um agente com acesso à chave sair do controle, revogue a chave no portal; a API recusa na próxima chamada e o MCP em até 60 segundos.

Relacionados

• Autenticação e Créditos, franquia e rate limit.
• Busca de empresas: os filtros que gerar_filtro produz e buscar_empresas aceita.
• Referência gerada do OpenAPI: cada operação com o campo x-mcp-tool.