Variables de entorno del servidor MCP de Omnifox

Todas las variables que acepta @omnifox/mcp-server, cuáles son obligatorias y en qué casos necesitas fijar el espacio de trabajo.

Aug 19, 2026

Mira este paso en el video · MCP: que una IA opere Omnifox

El servidor MCP se configura por completo con variables de entorno, que declaras en el bloque env de tu cliente de IA o exportas en el shell antes de arrancarlo.

Referencia

Variable ¿Obligatoria? Valor por defecto Para qué sirve
OMNIFOX_API_KEY Sí — Token personal (Sanctum) emitido en Configuración → Desarrollo → API Keys. Sin él, el servidor no arranca.
OMNIFOX_BASE_URL No https://omnifox.io/api/v1 URL base de la API. Solo se cambia para entornos de prueba.
OMNIFOX_WORKSPACE_ID No — Id numérico del espacio de trabajo. Ver la advertencia de abajo.
MCP_SERVER_MODE No stdio stdio para clientes de escritorio, http para despliegues remotos.
PORT No 8080 Puerto del modo http. Se ignora en stdio.
OMNIFOX_TIMEOUT_MS No 30000 Tiempo máximo por petición, en milisegundos.
OMNIFOX_MAX_RETRIES No 3 Reintentos ante 429 (respetando Retry-After) y ante errores 5xx pasajeros.

Sobre el espacio de trabajo

Cada clave creada en la pantalla de API Keys queda fijada a un espacio de trabajo: ese campo es obligatorio al crearla. Por eso, en la mayoría de los casos no necesitas OMNIFOX_WORKSPACE_ID.

Hay una excepción importante: la herramienta set_user_status manda el id del espacio dentro del cuerpo de la petición porque el endpoint lo exige. Si no defines OMNIFOX_WORKSPACE_ID, esa llamada responde 422. Si vas a cambiar la disponibilidad de agentes desde tu asistente, define la variable.

El id numérico del espacio lo puedes obtener pidiéndole a tu asistente que use la herramienta list_workspaces.

Ejemplo 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"
      }
    }
  }
}

Consejos

  • Sube OMNIFOX_TIMEOUT_MS si trabajas con listados grandes o reportes de rangos largos.
  • Bajar OMNIFOX_MAX_RETRIES a 0 es útil mientras depuras: ves el error real de inmediato en vez de esperar los reintentos.
  • No pongas OMNIFOX_BASE_URL apuntando a app.omnifox.io: la ruta canónica de la API es omnifox.io/api/v1.

Si algo no funciona

  • OMNIFOX_API_KEY is required: la variable no llegó al proceso. En Claude Desktop y Cursor tiene que ir dentro de env, no en args.
  • 422 al cambiar el estado de un agente: falta OMNIFOX_WORKSPACE_ID.
  • 404 en todo: la URL base quedó sin el /api/v1 final.

Artículos relacionados

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp