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.

Aug 19, 2026

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

  1. Reinicie o aplicativo por completo, não só a janela.
  2. 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.
  3. Verifique se o npx está no PATH com o qual o aplicativo é iniciado. Na dúvida, coloque o caminho absoluto do npx em command.
  4. 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 bloco env, não em args.
  • unknown MCP_SERVER_MODE=... — o valor não é stdio nem http; o servidor continua em stdio e 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

  • 422 ao alterar a disponibilidade de um agente. O set_user_status precisa do id do espaço de trabalho no corpo da requisição: defina OMNIFOX_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_window e, se estiver fechada, envie um modelo aprovado com send_message e type: whatsapp_template.
  • A reserva de um compromisso falha. O starts_at precisa ser exatamente um dos que o list_free_slots devolveu; se passou tempo, consulte de novo.
  • O assistente diz que não encontra um contato que existe. O search_contacts exige pelo menos 2 caracteres e busca por nome, e-mail e telefone; para buscar por id use get_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_RETRIES em 0: 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. Um 200 descarta o problema de credenciais.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp