O Conexa MCP conecta o Claude ao Conexa (conexa.app), sistema de gestão de coworkings e negócios recorrentes — e transforma toda a API v2 em 83 ferramentas que você aciona por conversa: vendas, clientes, contratos, cobranças, financeiro e reservas de sala.
01 · O que é
Um servidor MCP (Model Context Protocol) que roda na sua máquina e dá ao Claude acesso direto — e controlado — ao seu Conexa.
"Cadastre o cliente", "quais salas estão reservadas amanhã?", "crie a venda" — pedidos em linguagem natural viram chamadas reais à API.
Uma ferramenta para cada endpoint: 82 rotas da API v2 do Conexa, mais test_connection para validar a instalação.
As definições das ferramentas são geradas automaticamente da collection Postman oficial da Conexa — quando a API evolui, o servidor acompanha.
Token só no arquivo de configuração local, ações destrutivas marcadas (o Claude pede confirmação) e limite de requisições respeitado sozinho.
02 · Como funciona
Tudo roda na sua máquina. O servidor conversa direto com o seu Conexa — nenhum intermediário na internet.
"Liste as cobranças em aberto deste mês", "cadastre o cliente João da Silva", "quais salas estão reservadas para amanhã?".
Entre as 83 disponíveis — cada uma descreve seus campos e filtros a partir da documentação oficial, então o Claude sabe exatamente o que preencher.
Parâmetros de rota, filtros (aceitam múltiplos valores por vírgula), paginação com limit/offset e corpo JSON — tudo validado antes de sair.
Com o Token de Aplicação (recomendado) ou com usuário e senha — nesse modo o servidor faz o login sozinho, renova a sessão e reautentica automaticamente se ela expirar.
Fila local de 55 requisições por minuto (margem sob o limite oficial de 60) e espera automática quando a API pede para aguardar (HTTP 429).
JSON legível de volta ao Claude, que responde em português. Erro da API vira mensagem clara, com o status e o motivo — nada de falha silenciosa.
03 · Ferramentas
Organizadas por área do Conexa. Nomes reais — é exatamente isso que o Claude enxerga.
amarelo = ação destrutiva (excluir, encerrar, cancelar) — marcada no protocolo, o Claude pede sua confirmação antes de executar.
04 · Instalação guiada
Não precisa entender de programação: copie o prompt abaixo e cole em uma conversa com o Claude (Claude Code ou Claude Desktop). Ele verifica os pré-requisitos, oferece pilotar o navegador na hora de obter o token e só declara pronto depois de validar a conexão de verdade.
O Token de Aplicação é criado dentro do Conexa, em Config > Integrações > API / Token — o assistente oferece fazer essa parte por você, pilotando o navegador (você faz o login; a senha nunca passa pelo chat).
Quero instalar o servidor MCP do Conexa (https://github.com/Expert-Integrado/conexa-mcp) nesta máquina. Conduza o processo do início ao fim, nesta ordem, sem pular a validação final: 1. PRÉ-REQUISITOS — verifique com comandos reais: rode "node --version" (precisa ser 18 ou superior). Se o Node.js não estiver instalado, me oriente a instalar pelo site https://nodejs.org e só continue depois de confirmar. Identifique também qual cliente estou usando (Claude Code, Claude Desktop ou outro cliente MCP). 2. SUBDOMÍNIO — me pergunte o subdomínio do meu Conexa: é a primeira parte do endereço que uso para acessar o sistema (se acesso "minhaempresa.conexa.app", o subdomínio é "minhaempresa"). Não continue sem essa resposta. 3. TOKEN DE APLICAÇÃO (etapa de navegador) — o token é criado dentro do Conexa, no menu Config > Integrações > API / Token, por um usuário administrador. Antes de executar, pergunte com a ferramenta AskUserQuestion (botões; se o cliente não tiver botões, pergunte em texto): "Essa etapa é no navegador. Quer que eu faça para você?" com estas opções: - "Sim, pilote o navegador" (opção padrão): use o Playwright MCP; se ele não estiver instalado, instale antes com "claude mcp add playwright -- npx -y @playwright/mcp@latest" e me avise caso precise reiniciar a sessão. Abra https://SUBDOMINIO.conexa.app, PARE na tela de login e peça para eu fazer o login sozinho — NUNCA peça minha senha no chat. Depois que eu confirmar que entrei, navegue até Config > Integrações > API / Token e me ajude a gerar e copiar o Token de Aplicação. - "Usar o Claude in Chrome": mesmo roteiro, pilotando o meu Chrome (que já tem minha sessão logada). - "Prefiro fazer manualmente": me passe o passo a passo — acessar https://SUBDOMINIO.conexa.app com usuário administrador, abrir Config > Integrações > API / Token, gerar o token e colar aqui UMA única vez, só para ele ir direto para o arquivo de configuração local. 4. REGISTRO DO MCP — configure o servidor com as variáveis de ambiente corretas: - Claude Code: claude mcp add conexa --scope user --env CONEXA_SUBDOMAIN=--env CONEXA_TOKEN= -- npx -y conexa-mcp - Claude Desktop: adicione ao claude_desktop_config.json (menu Configurações > Desenvolvedor > Editar configuração) o servidor "conexa" com command "npx", args ["-y", "conexa-mcp"] e as variáveis CONEXA_SUBDOMAIN e CONEXA_TOKEN. - Outro cliente MCP: configuração equivalente (command: npx -y conexa-mcp + as duas variáveis). 5. SEGURANÇA — o token vive SOMENTE no arquivo de configuração local do MCP (ou em um .env local). Não repita o token na conversa depois de salvo, não grave em outros arquivos e nunca envie para a internet ou para um repositório. 6. VALIDAÇÃO REAL — peça para eu reiniciar o cliente (fechar e abrir) e então chame a ferramenta test_connection do servidor conexa. Só considere a credencial válida se a resposta confirmar que a conexão está funcionando. Se der erro, leia a mensagem (token errado, subdomínio errado e token expirado são as causas mais comuns) e me ajude a corrigir antes de seguir. 7. TESTE FINAL E RESUMO — faça uma chamada de leitura de verdade (por exemplo, list_companies com limit 1), me mostre o resultado e termine com um resumo: o que foi instalado, onde o token ficou salvo e 3 exemplos de pedidos que eu já posso fazer.
claude mcp add conexa --scope user \ --env CONEXA_SUBDOMAIN=minhaempresa \ --env CONEXA_TOKEN=seu_token_aqui \ -- npx -y conexa-mcp
Claude Desktop, execução a partir do código-fonte e solução de problemas: veja o guia de instalação completo.
| Variável | Obrigatória | Descrição |
|---|---|---|
CONEXA_SUBDOMAIN | Sim* | Subdomínio do seu Conexa (minhaempresa de minhaempresa.conexa.app) |
CONEXA_TOKEN | Sim** | Token de Aplicação (recomendado) — criado em Config > Integrações > API / Token |
CONEXA_USERNAME / CONEXA_PASSWORD | Alternativa** | Login de um usuário admin/funcionário; o servidor autentica e renova a sessão sozinho |
CONEXA_BASE_URL | Alternativa* | URL completa da API, para ambientes fora do padrão https://X.conexa.app/index.php/api/v2 |
* informe CONEXA_SUBDOMAIN ou CONEXA_BASE_URL · ** informe CONEXA_TOKEN ou usuário e senha.
05 · Stack
Duas dependências de runtime. O código que fala com a API tem ~140 linhas — dá para ler inteiro antes de confiar.