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.
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_MSse você trabalha com listagens grandes ou relatórios de períodos longos. - Baixar o
OMNIFOX_MAX_RETRIESpara0é útil enquanto você depura: você vê o erro real na hora, em vez de esperar as novas tentativas. - Não aponte o
OMNIFOX_BASE_URLparaapp.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 deenv, não emargs.422ao alterar o status de um agente: falta oOMNIFOX_WORKSPACE_ID.404em tudo: a URL base ficou sem o/api/v1no final.
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.