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.

Aug 19, 2026

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

  1. Restart the app completely, not just the window.
  2. Check that the configuration JSON is valid: one extra comma breaks the whole file and the client ignores it silently.
  3. Verify that npx is in the PATH the app starts with. If in doubt, put the absolute path to npx in command.
  4. 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 the env block, not in args.
  • unknown MCP_SERVER_MODE=... — the value is neither stdio nor http; the server stays on stdio and 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

  • 422 when changing an agent's availability. set_user_status needs the workspace id in the request body: set OMNIFOX_WORKSPACE_ID.
  • The WhatsApp message does not arrive and there is no clear error. The 24-hour window is closed. Check get_conversation_sending_window first and, if it is closed, send an approved template with send_message and type: whatsapp_template.
  • Booking an appointment fails. The starts_at has to be exactly one of the values list_free_slots returned; if time has passed, query them again.
  • The assistant says it cannot find a contact that does exist. search_contacts requires at least 2 characters and searches by name, email, and phone; to search by id use get_contact.
  • Everything is slow or cuts off. Raise OMNIFOX_TIMEOUT_MS; the default is 30 seconds per request.

Tips

  • While debugging, set OMNIFOX_MAX_RETRIES to 0: 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. A 200 rules out a credentials problem.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp