Solução de problemas do servidor MCP da Omnifox
Os erros mais comuns ao usar o @omnifox/mcp-server e o que revisar em cada caso, da inicialização aos códigos da API.
Veja este passo no vídeo · Solução de problemas
Guia rápido para quando o servidor MCP da Omnifox não responde como você espera. As mensagens do servidor são escritas em stderr, então revise o registro do seu cliente de IA: é ali que elas aparecem.
Não aparece nenhuma ferramenta no cliente
- Reinicie o aplicativo por completo, não só a janela.
- Confira se o JSON de configuração é válido: uma vírgula a mais quebra o arquivo inteiro e o cliente o ignora em silêncio.
- Verifique se o
npxestá no PATH com o qual o aplicativo é iniciado. Na dúvida, coloque o caminho absoluto donpxemcommand. - Confira a versão do Node: é necessário 18.17 ou superior.
O servidor não inicia
OMNIFOX_API_KEY is required— a variável não chegou ao processo. Ela precisa ficar no blocoenv, não emargs.unknown MCP_SERVER_MODE=...— o valor não éstdionemhttp; o servidor continua emstdioe avisa pelo stderr.
Códigos de erro da API
| Código | O que significa | O que fazer |
|---|---|---|
401 |
Token inválido, revogado ou vencido. | Emita uma chave nova em Configurações → Desenvolvimento → API Keys. |
402 / PLAN_API_ACCESS_REQUIRED |
O plano não inclui Acesso à API, ou o módulo consultado não está no plano. | O Acesso à API está disponível a partir do plano Crece. |
403 |
Falta à chave o scope daquele módulo. | Edite a chave e adicione a permissão (read:crm, write:projects, etc.). |
404 |
O registro não existe no espaço de trabalho da chave. | Os ids são por espaço; verifique se a chave aponta para o correto. |
422 |
Faltam campos ou eles vêm errados. | A mensagem de erro traz o detalhe campo por campo. |
429 |
Você passou do limite de requisições por minuto do seu plano. | O servidor tenta de novo sozinho, respeitando o Retry-After, até OMNIFOX_MAX_RETRIES vezes. |
Casos concretos que confundem
422ao alterar a disponibilidade de um agente. Oset_user_statusprecisa do id do espaço de trabalho no corpo da requisição: definaOMNIFOX_WORKSPACE_ID.- A mensagem de WhatsApp não chega e não há erro claro. A janela de 24 horas está fechada. Consulte primeiro
get_conversation_sending_windowe, se estiver fechada, envie um modelo aprovado comsend_messageetype: whatsapp_template. - A reserva de um compromisso falha. O
starts_atprecisa ser exatamente um dos que olist_free_slotsdevolveu; se passou tempo, consulte de novo. - O assistente diz que não encontra um contato que existe. O
search_contactsexige pelo menos 2 caracteres e busca por nome, e-mail e telefone; para buscar por id useget_contact. - Tudo está lento ou cai. Aumente o
OMNIFOX_TIMEOUT_MS; o valor padrão é 30 segundos por requisição.
Dicas
- Enquanto você depura, coloque o
OMNIFOX_MAX_RETRIESem0: o erro real aparece na hora, em vez de depois de três tentativas. - Se você suspeitar do token, teste-o à parte com
curl:curl -H "Authorization: Bearer TU_TOKEN" https://omnifox.io/api/v1/contacts. Um200descarta o problema de credenciais.
Artigos relacionados
Artigos relacionados
-
Como conectar integrações e apps externos
Conecte o Omnifox às suas ferramentas favoritas a partir do catálogo de integrações em poucos passos.
-
Integrar o Omnifox com Azur, Siigo, Alegra, QuickBooks ou outro sistema contábil ou ERP
O Omnifox não tem hoje um conector nativo com sistemas contábeis ou ERP. Veja como fazer essa conexão mesmo assim com fluxos de trabalho, o nó HTTP, n8n, Make, Zapier ou a API, com exemplos.
-
Guia completo de integrações e API
Integrações e API a fundo, em 30 capítulos: chaves de API, chamadas reais, webhooks assinados, n8n, MCP e SDKs, tudo funcionando de verdade.
-
Gerar e usar API keys e webhooks
Crie chaves de API para acessar o Omnifox por código e configure webhooks para receber eventos em tempo real.
-
Introdução às integrações (webhook / OAuth / chave de API)
Conecte o Omnifox às suas outras ferramentas: o que está disponível hoje, o que chega em breve e quando usar um webhook, uma conexão OAuth ou uma chave de API.