Omnifox MCP server environment variables
Every variable @omnifox/mcp-server accepts, which ones are required, and when you need to pin the workspace.
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_MSif you work with large listings or reports over long ranges. - Lowering
OMNIFOX_MAX_RETRIESto0is useful while debugging: you see the real error right away instead of waiting through the retries. - Do not point
OMNIFOX_BASE_URLatapp.omnifox.io: the canonical API path isomnifox.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 insideenv, not inargs.422when changing an agent's status:OMNIFOX_WORKSPACE_IDis missing.404on everything: the base URL is missing the trailing/api/v1.
Related articles
Related articles
-
How to connect integrations and external apps
Connect Omnifox with your favorite tools from the integrations catalog in just a few steps.
-
Integrations and API complete guide
Integrations and API in depth, in 30 chapters: API keys, real calls, signed webhooks, n8n, MCP and SDKs, all really working.
-
Connecting Omnifox to Azur, Siigo, Alegra, QuickBooks or another accounting system or ERP
Omnifox doesn't have a native connector for accounting systems or ERPs today. Here's how to connect them anyway with workflows, the HTTP node, n8n, Make, Zapier or the API, with examples.
-
Generate and use API keys and webhooks
Create API keys to access Omnifox programmatically and set up webhooks to receive real-time events.
-
Getting started with integrations (webhook / OAuth / API key)
Connect Omnifox with your other tools: what's available today, what's coming soon, and when to use a webhook, an OAuth connection or an API key.