---
title: "Servidor MCP do cnpj.ia.br"
description: "Conecte Claude, Cursor, Windsurf ou um agente OpenAI à base de empresas do Brasil. Quatro ferramentas, a mesma chave da API, o mesmo custo em créditos e a chave sempre no cliente do agente."
canonical: "https://cnpj.ia.br/docs/mcp"
date_modified: 2026-09-02
source: "cnpj.ia.br"
---

docs · base agosto/2026 Atualizado em 02/09/2026

# Servidor MCP do cnpj.ia.br

Conecte Claude, Cursor, Windsurf ou um agente OpenAI à base de empresas do Brasil. Quatro ferramentas, a mesma chave da API, o mesmo custo em créditos e a chave sempre no cliente do agente.

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 a mesma chave e o mesmo custo em créditos da API REST. A chave 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

Transporte HTTP, autenticação pela chave da conta no header `Authorization`. Crie a chave em [app.cnpj.ia.br](https://app.cnpj.ia.br) e cole no cliente:

#### Claude Desktop

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

#### 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_..." }
    }
  }
}
```

#### Windsurf

```json
{
  "mcpServers": {
    "cnpjia": {
      "serverUrl": "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="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

| Ferramenta | Operação da API | Créditos | Planos |
| --- | --- | --- | --- |
| `consultar_cnpj` | `GET /v1/cnpjs/{cnpj}` | 1 em `basic`, 6 em `full` | todos |
| `buscar_empresas` | `GET /v1/cnpjs` | 1 por empresa retornada, até 20 por página | pagos; no Free responde `insufficient_plan` |
| `gerar_filtro` | `POST /v1/filters/generate` | 1 por chamada | todos |
| `ver_uso` | `GET /v1/usage` | 0 | todos |

`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`](https://cnpj.ia.br/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 não a guarda, não abre sessão sem ela 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](https://cnpj.ia.br/docs/autenticacao) e [Créditos, franquia e rate limit](https://cnpj.ia.br/docs/creditos-e-limites).
- [Busca de empresas](https://cnpj.ia.br/docs/busca-empresas): os filtros que `gerar_filtro` produz e `buscar_empresas` aceita.
- [Referência gerada do OpenAPI](https://cnpj.ia.br/docs/referencia): cada operação com o campo `x-mcp-tool`.

## 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 no ChatGPT e em agentes OpenAI?**

Em agentes construídos com a API da OpenAI, sim: a ferramenta `mcp` da Responses API aceita `server_url` e `headers`, como no exemplo da página. No app ChatGPT a conexão depende do que a OpenAI habilita para conectores MCP com autenticação por header na sua conta.

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

Não. O servidor MCP só expõe consulta, busca, geração de filtro e leitura de uso. Compra de pacote e troca de plano acontecem no portal, por uma pessoa autenticada.

**O custo pelo MCP é o mesmo da API?**

Sim. Cada ferramenta chama a operação correspondente da API e debita os mesmos créditos: uma consulta `full` pelo agente custa o que custaria por `curl`. O agente vê o saldo com `ver_uso`.

**Por que a busca aparece na lista de ferramentas se meu plano é Free?**

Porque a lista é a mesma para toda conta, e o agente precisa saber que a ferramenta existe para explicar ao usuário por que não pode usá-la. No Free ela responde `insufficient_plan` com um link para os planos, sem consumir crédito.