Guia de configuração do Clara MCP para ferramentas de IA

Antes de começar: Você precisa de um token do Clara MCP. Se você ainda não tiver um, entre em contato com seu Agente Clara ou com a nossa equipe de atendimento (pelo contato@clara.com) para solicitar acesso. Veja Clara MCP — O que é e como obter acesso

O que você vai precisar

• Um token do Clara MCP (fornecido pela equipe da Clara).
• Uma das ferramentas de IA suportadas:
  • Claude Desktop (macOS ou Windows): totalmente suportado, guia passo a passo abaixo.
  • Claude Code (CLI): totalmente suportado, guia passo a passo abaixo.
  • Outras ferramentas compatíveis com MCP (ChatGPT, Gemini, etc.): veja a configuração genérica ao final deste guia.

Opção A — Claude Desktop (recomendado)

O Claude Desktop é a maneira mais fácil de usar o Clara MCP. Ele roda no seu computador Mac ou Windows.

Passo 1 — Instalar o Node.js (se você não tiver)

O Claude Desktop usa uma pequena ferramenta de ponte chamada supergateway para se conectar à Clara. Isso requer que o Node.js esteja instalado.

• Se você usa Mac:
  Abra um terminal e digite: npx

Se você vir uma resposta começando com Entering npm script environment, está tudo certo. Pule para o Passo 2.

Se não tiver instalado, você pode instalá-lo de duas formas:

Opção 1 — Com Homebrew:

brew install node

Opção 2 — Baixe o instalador diretamente em nodejs.org e execute-o.

Se você usa Windows:

Abra o Command Prompt ou PowerShell e digite:

node --version

Se você vir um número de versão (por exemplo, v20.x.x), já está pronto. Pule para o Passo 2.

Se não tiver instalado:

1. Acesse nodejs.org e baixe o instalador .msi para Windows.
2. Execute-o e siga os passos do assistente de instalação (deixe todas as opções como padrão).
3. Verifique novamente com node --version para confirmar que a instalação foi concluída corretamente.

Passo 2 — Editar seu arquivo de configuração do Claude Desktop

Abra este arquivo no seu computador:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Adicione o seguinte bloco dentro do objeto mcpServers. Se o arquivo estiver vazio ou for novo, use a estrutura completa abaixo:

JSON

{
 "mcpServers": {
   "clara-mcp": {
     "command": "npx",
     "args": [
       "-y",
       "supergateway",
       "--streamableHttp",
       "https://api-prod.br.clara.com/mcp",
       "--header",
       "clara-mcp-token: SEU_TOKEN_AQUI"
     ]
   }
 }
}
 

Substitua SEU_TOKEN_AQUI pelo token fornecido pela equipe da Clara. Mantenha o restante exatamente como mostrado.

Dica de segurança: Este arquivo contém seu token. Não o compartilhe nem o envie para nenhum sistema de controle de versão.

Passo 3 — Reiniciar o Claude Desktop

Encerre completamente o Claude Desktop (não apenas feche a janela — use a opção Sair/Quit no menu) e abra-o novamente.

Quando ele abrir, você verá o clara-mcp listado nas ferramentas disponíveis do Claude.

Passo 4 — Teste

Pergunte ao Claude algo como:

• “Listar meus cartões Clara”
• “Mostrar minhas últimas 10 transações”
• “Bloquear o cartão com final 3540”

O Claude se conectará à Clara em tempo real e responderá.

Opção B — Claude Code (CLI)

Se você usa o Claude Code no terminal, adicione o Clara MCP como um servidor HTTP:

Bash

claude mcp add clara-mcp \
--transport http \
--url https://api-prod.br.clara.com/mcp \
--header "clara-mcp-token: SEU_TOKEN_AQUI"
 

Substitua SEU_TOKEN_AQUI pelo seu token. Agora você pode usar o Clara MCP em qualquer sessão do Claude Code.

Opção C — Outras ferramentas compatíveis com MCP (ChatGPT, Gemini, etc.)

O Clara MCP utiliza o protocolo MCP padrão, portanto funciona com qualquer ferramenta de IA compatível. Os passos exatos de configuração variam de acordo com a ferramenta — consulte a documentação da sua ferramenta para saber como adicionar um servidor MCP personalizado.

Quando solicitado, use estes valores:

Se precisar de ajuda para configurar uma ferramenta específica, entre em contato com nosso time de atendimento e nós te guiaremos.

Verifique sua conexão

Uma vez configurado em qualquer ferramenta, teste a conexão perguntando:

“Listar meus cartões Clara”

Se você vir uma lista de cartões da conta da sua empresa, você está conectado corretamente.

Se receber um erro, consulte a seção de solução de problemas abaixo.

Solução de problemas

• “Nenhuma ferramenta encontrada” ou o Clara MCP não aparece
  • Certifique-se de que reiniciou completamente a ferramenta de IA após editar a configuração (encerrar e abrir novamente, não apenas atualizar).
  • Verifique o arquivo de configuração em busca de erros de digitação — o JSON é sensível à falta de vírgulas e aspas.
  • Confirme se o npx está disponível no seu terminal (apenas para Claude Desktop).
• Erro “Não autorizado” ou “401”
  • Seu token pode estar incorreto ou expirado — entre em contato com seu Agente Clara ou Customer Happiness para verificar.
  • Certifique-se de que o cabeçalho seja exatamente clara-mcp-token (em minúsculas, com hifens).
• “Conexão recusada” ou servidor inacessível
  • Verifique sua conexão com a internet.
  • O servidor Clara MCP pode estar temporariamente indisponível — tente novamente em alguns minutos.
• Bloquear/desbloquear cartão retorna uma mensagem simples de “Ok”
  • Esta é uma limitação conhecida da fase Beta. A operação foi executada corretamente, mesmo que a resposta pareça simples. O cartão foi bloqueado/desbloqueado com sucesso.
• A contagem de transações mostra 0
  • Este é um problema conhecido da Beta com o contador de resumo. As transações reais são retornadas corretamente na lista.

Gerenciando seu token

• Seu token é exibido apenas uma vez quando emitido. Guarde-o em um local seguro (um gerenciador de senhas é o ideal).
• Para revogar seu token: entre em contato com o Customer Happiness ou com a equipe de Solution Engineering. Seu token será invalidado imediatamente em todas as ferramentas onde estiver configurado.
• Para obter um novo token: entre em contato com a mesma equipe após a revogação. Você precisará atualizar o token no seu arquivo de configuração e reiniciar sua ferramenta de IA.

Em breve: Geração, rotação e revogação de tokens estarão disponíveis diretamente em Configurações → Integrações → Clara MCP na Clara — sem necessidade de entrar em contato com a equipe.

Referência do servidor Clara MCP

Última atualização: Maio de 2026 · Clara MCP está em Beta