Troubleshooting the Omnifox MCP server
The most common errors when using @omnifox/mcp-server and what to check in each case, from startup to API codes.
Watch this step in the video · Troubleshooting
A quick guide for when the Omnifox MCP server does not behave the way you expect. The server's messages are written to stderr, so check your AI client's log: that is where they show up.
No tools show up in the client
- Restart the app completely, not just the window.
- Check that the configuration JSON is valid: one extra comma breaks the whole file and the client ignores it silently.
- Verify that
npxis in the PATH the app starts with. If in doubt, put the absolute path tonpxincommand. - Check the Node version: 18.17 or higher is required.
The server does not start
OMNIFOX_API_KEY is required— the variable never reached the process. It has to go in theenvblock, not inargs.unknown MCP_SERVER_MODE=...— the value is neitherstdionorhttp; the server stays onstdioand says so on stderr.
API error codes
| Code | What it means | What to do |
|---|---|---|
401 |
Invalid, revoked, or expired token. | Issue a new key in Settings → Development → API Keys. |
402 / PLAN_API_ACCESS_REQUIRED |
The plan does not include API Access, or the module you queried is not in the plan. | API Access is available from the Crece plan up. |
403 |
The key is missing that module's scope. | Edit the key and add the permission (read:crm, write:projects, etc.). |
404 |
The record does not exist in the key's workspace. | Ids are per workspace; check that the key points to the right one. |
422 |
Fields are missing or malformed. | The error message carries the detail field by field. |
429 |
You exceeded your plan's requests-per-minute limit. | The server retries on its own, honoring Retry-After, up to OMNIFOX_MAX_RETRIES times. |
Specific cases that trip people up
422when changing an agent's availability.set_user_statusneeds the workspace id in the request body: setOMNIFOX_WORKSPACE_ID.- The WhatsApp message does not arrive and there is no clear error. The 24-hour window is closed. Check
get_conversation_sending_windowfirst and, if it is closed, send an approved template withsend_messageandtype: whatsapp_template. - Booking an appointment fails. The
starts_athas to be exactly one of the valueslist_free_slotsreturned; if time has passed, query them again. - The assistant says it cannot find a contact that does exist.
search_contactsrequires at least 2 characters and searches by name, email, and phone; to search by id useget_contact. - Everything is slow or cuts off. Raise
OMNIFOX_TIMEOUT_MS; the default is 30 seconds per request.
Tips
- While debugging, set
OMNIFOX_MAX_RETRIESto0: the real error shows up immediately instead of after three retries. - If you suspect the token, test it separately with
curl:curl -H "Authorization: Bearer TU_TOKEN" https://omnifox.io/api/v1/contacts. A200rules out a credentials problem.
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.