O MCP (Model Context Protocol) é o padrão aberto que permite que assistentes de IA, como o Claude e o Cursor, usem ferramentas externas durante a conversa. Com o MCP da APIBrasil, o assistente passa a consultar CEP, CNPJ, CPF, placas de veículos e outras APIs brasileiras sozinho: você pede em português e ele faz a chamada.
Neste tutorial você vai configurar o servidor MCP da APIBrasil no Claude Desktop e no Cursor, testar a conexão e ver ideias de uso no dia a dia.
O que muda com o MCP
Sem MCP, para consultar um CNPJ você precisa escrever a requisição, montar o corpo e tratar a resposta. Com MCP, o assistente recebe a lista de ferramentas da APIBrasil, entende o que cada uma faz e decide qual chamar a partir do seu pedido.
| Sem MCP | Com MCP |
|---|---|
| Você escreve a requisição HTTP | Você pede em linguagem natural |
| Monta o corpo e os cabeçalhos | O assistente escolhe a ferramenta certa |
| Lê o JSON de resposta | O assistente resume o resultado para você |
Segundo a documentação de MCP da APIBrasil, há guias para 6 ferramentas que falam o protocolo (Claude Desktop, Cursor, Visual Studio Code, Zed, Node.js/TypeScript e Python) e mais 4 guias que usam o gateway REST, para ferramentas que ainda não suportam MCP.
Pré-requisitos
- Uma conta ativa na APIBrasil, criada em app.apibrasil.io, com saldo para as consultas.
- O Claude Desktop instalado (claude.ai/download) ou o Cursor.
Configurando no Claude Desktop
1. Encontre o arquivo de configuração
O Claude Desktop lê os servidores MCP do arquivo claude_desktop_config.json:
| Sistema | Caminho |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
Se o arquivo não existir, crie. Pelo próprio app, o caminho mais fácil é abrir as configurações, ir em Desenvolvedor e clicar para editar a configuração.
2. Adicione o servidor da APIBrasil
Cole a configuração publicada na documentação:
{
"mcpServers": {
"mcp.apibrasil.cloud/mcp": {
"name": "APIBrasil MCP",
"url": "https://mcp.apibrasil.cloud/mcp"
}
}
}
Se você já tem outros servidores MCP configurados, adicione só o bloco da APIBrasil dentro de mcpServers, separando com vírgula. Um JSON mal formatado, com vírgula sobrando no final, é a causa mais comum de o servidor não aparecer.
3. Confirme o endereço e reinicie
Garanta que o endpoint seja exatamente https://mcp.apibrasil.cloud/mcp. Depois, feche o Claude Desktop por completo (não basta fechar a janela) e abra de novo.
4. Teste a conexão
Pergunte ao Claude: *”Quais ferramentas MCP você tem disponíveis?”*. As APIs da APIBrasil devem aparecer na lista. Em seguida, faça um teste real:
Consulte informações sobre o CEP 01310-100
Configurando no Cursor
No Cursor, os servidores MCP ficam em um arquivo mcp.json: global, em ~/.cursor/mcp.json, ou por projeto, em .cursor/mcp.json na raiz do repositório. Adicione o servidor da APIBrasil:
{
"mcpServers": {
"apibrasil": {
"url": "https://mcp.apibrasil.cloud/mcp"
}
}
}Depois, abra as configurações do Cursor na seção de MCP e confira se o servidor aparece como ativo. No chat do agente, peça algo como *”valide o CNPJ 44.959.669/0001-80 e me diga a situação cadastral”*.
A documentação da APIBrasil tem guias específicos para Cursor, VS Code e Zed em doc.apibrasil.io/mcp, com o passo a passo de cada editor.
Ideias de uso no dia a dia
- Atendimento e vendas: “Confira se este CNPJ está ativo e qual o CNAE principal.”
- Cadastro: “Qual o endereço completo do CEP 30130-010?”
- Desenvolvimento: no Cursor, “Gere um cliente TypeScript para a API de placa FIPE e teste com a placa ABC1D23 em homologação.”
- Análises rápidas: “Liste as cidades de Minas Gerais com DDD 31.”
Cuidados importantes
- As consultas continuam sendo cobradas. Quando o assistente chama uma API em produção, o valor sai do seu saldo, como em qualquer chamada.
- Dados pessoais: consultas de CPF envolvem dados protegidos pela LGPD. Use só quando houver finalidade legítima e evite colar os resultados em conversas compartilhadas.
- Revise antes de agir: o assistente resume a resposta, mas decisões importantes, como aprovar crédito, devem se basear nos dados originais.
Solução de problemas
| Sintoma | O que verificar |
|---|---|
| O servidor não aparece | JSON válido, arquivo no caminho certo e app reiniciado por completo |
| Ferramentas aparecem, mas a chamada falha | Conta ativa e saldo disponível no painel |
| O assistente não usa a ferramenta | Seja explícito: “use a APIBrasil para consultar…” |
Perguntas frequentes
Preciso saber programar para usar o MCP?
Não. No Claude Desktop, basta editar o arquivo de configuração uma vez. Depois disso é só conversar.
Qual a diferença entre MCP e usar a API direto?
O MCP é ideal para uso interativo e para acelerar o desenvolvimento. Para sistemas em produção, integre a API diretamente no seu back-end, com tratamento de erros e controle de custo. Veja boas práticas para integrar a APIBrasil em produção.
Próximos passos
Se quer entender o que acontece por trás das ferramentas, veja os primeiros passos na APIBrasil e o tutorial de consulta de CNPJ com Python.
