Omnifox MCP server environment variables

Every variable @omnifox/mcp-server accepts, which ones are required, and when you need to pin the workspace.

Aug 19, 2026

Watch this step in the video · MCP: let an AI operate Omnifox

The MCP server is configured entirely with environment variables, which you declare in the env block of your AI client or export in the shell before starting it.

Reference

Variable Required? Default What it does
OMNIFOX_API_KEY Yes — Personal token (Sanctum) issued in Settings → Development → API Keys. Without it, the server does not start.
OMNIFOX_BASE_URL No https://omnifox.io/api/v1 Base URL of the API. Change it only for test environments.
OMNIFOX_WORKSPACE_ID No — Numeric workspace id. See the warning below.
MCP_SERVER_MODE No stdio stdio for desktop clients, http for remote deployments.
PORT No 8080 Port for http mode. Ignored in stdio.
OMNIFOX_TIMEOUT_MS No 30000 Maximum time per request, in milliseconds.
OMNIFOX_MAX_RETRIES No 3 Retries on 429 (honoring Retry-After) and on transient 5xx errors.

About the workspace

Every key created on the API Keys screen is tied to one workspace: that field is required when you create it. That is why, in most cases, you do not need OMNIFOX_WORKSPACE_ID.

There is one important exception: the set_user_status tool sends the workspace id in the request body because the endpoint requires it. If you do not set OMNIFOX_WORKSPACE_ID, that call responds 422. If you are going to change agent availability from your assistant, set the variable.

You can get the numeric workspace id by asking your assistant to use the list_workspaces tool.

Full example

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

Tips

  • Raise OMNIFOX_TIMEOUT_MS if you work with large listings or reports over long ranges.
  • Lowering OMNIFOX_MAX_RETRIES to 0 is useful while debugging: you see the real error right away instead of waiting through the retries.
  • Do not point OMNIFOX_BASE_URL at app.omnifox.io: the canonical API path is omnifox.io/api/v1.

If something does not work

  • OMNIFOX_API_KEY is required: the variable never reached the process. In Claude Desktop and Cursor it has to go inside env, not in args.
  • 422 when changing an agent's status: OMNIFOX_WORKSPACE_ID is missing.
  • 404 on everything: the base URL is missing the trailing /api/v1.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp