Variáveis de ambiente do servidor MCP da Omnifox

Todas as variáveis que o @omnifox/mcp-server aceita, quais são obrigatórias e em que casos você precisa fixar o espaço de trabalho.

Aug 19, 2026

Veja este passo no vídeo · MCP: que uma IA opere o Omnifox

O servidor MCP é configurado inteiramente por variáveis de ambiente, que você declara no bloco env do seu cliente de IA ou exporta no shell antes de iniciá-lo.

Referência

Variável Obrigatória? Valor padrão Para que serve
OMNIFOX_API_KEY Sim — Token pessoal (Sanctum) emitido em Configurações → Desenvolvimento → API Keys. Sem ele, o servidor não inicia.
OMNIFOX_BASE_URL Não https://omnifox.io/api/v1 URL base da API. Só se altera para ambientes de teste.
OMNIFOX_WORKSPACE_ID Não — Id numérico do espaço de trabalho. Veja o aviso abaixo.
MCP_SERVER_MODE Não stdio stdio para clientes de desktop, http para implantações remotas.
PORT Não 8080 Porta do modo http. É ignorada no stdio.
OMNIFOX_TIMEOUT_MS Não 30000 Tempo máximo por requisição, em milissegundos.
OMNIFOX_MAX_RETRIES Não 3 Novas tentativas em caso de 429 (respeitando Retry-After) e de erros 5xx passageiros.

Sobre o espaço de trabalho

Cada chave criada na tela de API Keys fica presa a um espaço de trabalho: esse campo é obrigatório na criação. Por isso, na maioria dos casos você não precisa do OMNIFOX_WORKSPACE_ID.

Há uma exceção importante: a ferramenta set_user_status envia o id do espaço dentro do corpo da requisição porque o endpoint exige. Se você não definir OMNIFOX_WORKSPACE_ID, essa chamada responde 422. Se você vai alterar a disponibilidade de agentes a partir do seu assistente, defina a variável.

O id numérico do espaço você consegue pedindo ao seu assistente que use a ferramenta list_workspaces.

Exemplo completo

{
  "mcpServers": {
    "omnifox": {
      "command": "npx",
      "args": ["-y", "@omnifox/mcp-server"],
      "env": {
        "OMNIFOX_API_KEY": "tu-token-aqui",
        "OMNIFOX_WORKSPACE_ID": "1",
        "OMNIFOX_TIMEOUT_MS": "45000"
      }
    }
  }
}

Dicas

  • Aumente o OMNIFOX_TIMEOUT_MS se você trabalha com listagens grandes ou relatórios de períodos longos.
  • Baixar o OMNIFOX_MAX_RETRIES para 0 é útil enquanto você depura: você vê o erro real na hora, em vez de esperar as novas tentativas.
  • Não aponte o OMNIFOX_BASE_URL para app.omnifox.io: a rota canônica da API é omnifox.io/api/v1.

Se algo não funcionar

  • OMNIFOX_API_KEY is required: a variável não chegou ao processo. No Claude Desktop e no Cursor ela precisa ficar dentro de env, não em args.
  • 422 ao alterar o status de um agente: falta o OMNIFOX_WORKSPACE_ID.
  • 404 em tudo: a URL base ficou sem o /api/v1 no final.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp