Skip to main content

​
Quick test

To check everything is working, ask your client: “What data entities are available in our Jedify platform?”
  • Working — you get a response describing your organization’s data entities.
  • Not working — see the sections below.

​
Setup issues

​
Jedify tools not available

Symptoms: your client doesn’t recognize Jedify tools or says they’re unavailable. Solutions:
  1. Check the config file location:
    • Claude Desktop — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Cursor — macOS/Linux: ~/.cursor/mcp.json; Windows: %APPDATA%\Cursor\mcp.json
  2. Verify JSON format: no trailing commas, no missing quotes.
  3. Restart your client: quit completely and reopen.
  4. Check Node.js: run node --version to confirm Node.js 18+ is installed.
See Connect for the full setup steps.

​
Browser login keeps failing

Symptoms: the browser opens for sign-in but never completes, or you see an authentication error. Solutions:
  1. Clear browser data: clear cookies and try again in a private/incognito window.
  2. Check account access: confirm you can sign in to your organization’s Jedify platform directly.
  3. Contact your administrator: they may need to verify your account access.

​
Browser doesn’t open for sign-in

Symptoms: sign-in is required but no browser launches. Solutions:
  1. Open it manually: look for the sign-in URL in your client and open it in your browser.
  2. Check your default browser: make sure one is set in your system settings.
  3. Check security software: antivirus or firewall tools can block the browser launch.

​
API key not working

Symptoms: you set JEDIFY_API_KEY but requests still aren’t authenticated. Solutions:
  1. Use a user-bound key: the key must be bound to a user. Ask your Jedify administrator to issue one.
  2. Check the version: API-key authentication requires @jedify/mcp-auth v1.1.0 or later.
  3. Check the env block: confirm JEDIFY_API_KEY is inside env, not args. If it’s unset, the proxy falls back to the browser login.
See Authentication for the full configuration.

​
Builder mode issues

​
Builder tools or functions aren’t showing

Symptoms: list_semantic_functions is missing, or returns nothing. Solutions:
  1. Confirm Builder mode: your args must include --builder (see Modes).
  2. Using an API key? The mode is carried by the key (Asker by default), so requesting Builder mode elsewhere may not take effect. Set it in the server URL instead — "REMOTE_MCP_URL": "https://be.jedify.com/mcp/message?mode=builder" (see Select a mode with an API key).
  3. Check for existing functions: your account may not have any functions yet — create one from a validated question with create_semantic_function.
  4. Broaden your search: try a single keyword, or call list_semantic_functions with no filter.

​
SDK calls return 401

Symptoms: jedify.call(...) fails with an authentication error. Solution: confirm JEDIFY_API_KEY is set and valid in your app’s secrets.

​
A function failed validation

Symptoms: a created function has a “failed validation” status and can’t be called. Solutions:
  1. Re-validate the question: confirm the underlying question returns correct data in Asker mode.
  2. Recreate the function: create it again from a corrected inquiry.

​
Data access issues

​
”No data available” messages

Symptoms: tools work but return no data or “no entities found”. Solutions:
  1. Check data permissions: confirm with your administrator that you have access to the data you’re querying.
  2. Verify data setup: confirm your organization has data sources connected in Jedify.
  3. Test basic access: ask your client to use the contextualize tool to see what’s available.

​
Slow or incomplete results

Symptoms: queries take a long time or don’t finish. Solutions:
  1. Be more specific: use exact date ranges and filters instead of broad queries.
  2. Break down large requests: split complex analysis into smaller questions.

​
Connection issues

​
Connection timeouts

Solutions:
  1. Check your internet connection.
  2. Restart your client to reset the connection.
  3. Try again later — temporary network issues may resolve on their own.

​
Getting help

Before contacting support, collect:
  • Your operating system and client (Claude Desktop / Cursor)
  • What you were trying to do
  • The exact error message
  • Whether authentication completed
Who to contact:
  1. Jedify administrator — data access, account, or permission issues
  2. IT support — network, firewall, or system configuration
Self-service: