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 list the Jedify connector or tools, or says they’re unavailable. Solutions:
  1. Claude connector: open Settings → Connectors — Jedify should be listed and connected. If it’s missing, connect it from claude.ai/directory/jedify or ask your workspace admin to enable it for you.
  2. Local client — 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
    • Claude Code — ~/.claude.json
  3. Verify JSON format: no trailing commas, no missing quotes.
  4. Restart your client: quit completely and reopen.
  5. Check Node.js: run node --version to confirm Node.js 18+ is installed.
  6. Hosted agent or other MCP client? Check the server URL: it must be https://be.jedify.com/mcp, with ?mode=editor or ?mode=builder for the other modes — no other path.
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.

​
Sign-in page doesn’t open

Symptoms: sign-in is required but no browser or sign-in window appears. Solutions:
  1. Claude connector: allow pop-ups for Claude in your browser and click Connect again.
  2. Local client: look for the sign-in URL in your client’s output and open it manually; make sure a default browser 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 (or entered an API key in your platform) but requests still aren’t authenticated. Solutions:
  1. Use a key created in Jedify: create it under Settings → API Keys — keys created there are bound to you. A key issued any other way must be user-bound.
  2. Check the key is still active: keys can carry an expiry and can be deactivated or revoked under Settings → API Keys. Create a new one if in doubt.
  3. Local proxy — check the version: API-key authentication requires @jedify/mcp-auth v1.1.0 or later.
  4. Local proxy — 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.
  5. Hosted agent: the key belongs in the platform’s API key (or token) field for the Jedify MCP server.
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: Builder mode isn’t available through the Claude connector (Asker only). In a local client, set "REMOTE_MCP_URL": "https://be.jedify.com/mcp/message?mode=builder" in the env block — --builder and MCP_MODE are not reliable; for hosted agents, the server URL must be https://be.jedify.com/mcp?mode=builder (see Switching modes).
  2. Check for existing functions: your account may not have any functions yet — create one from a validated question with create_semantic_function.
  3. 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.

​
Editor mode issues

​
Editor tools aren’t showing

Symptoms: make_edit, get_graph, or the test-set tools are missing. Solution: Editor mode isn’t available through the Claude connector (Asker only). In a local client, set "REMOTE_MCP_URL": "https://be.jedify.com/mcp/message?mode=editor" in the env block — --editor and MCP_MODE are not reliable; for hosted agents, the server URL must be https://be.jedify.com/mcp?mode=editor (see Switching modes).

​
A versioning tool says it isn’t available for this account

Symptoms: list_versions, switch, compare_changes, or restore_version returns an error saying the operation isn’t available. Solution: these tools require Model Versioning to be enabled for your account. Editing still works without it — your agent uses make_edit, publish_change, and discard_change, and a Data Expert approves the edit in Jedify.

​
publish_change returned needs_confirmation

Symptoms: your agent reports that nothing was published and asks whether to proceed. Solution: this is expected. Publishing always requires your explicit confirmation; once you agree, your agent calls publish_change again with confirm: true.

​
make_edit returned status: "processing"

Symptoms: the edit was accepted but isn’t live, and your agent reports a changeset_id. Solution: the edit was submitted for review. Your agent polls sl_get_edit_state until each operation is confirmed; a Data Expert then approves the edit in Jedify before it can be published. See How an edit flows.

​
API-source tools are missing

Symptoms: call_api or the sl_*_api_* tools don’t appear. Solution: they are listed only when your account has a connected API source (such as HubSpot). Questions about API data go through ask_a_single_question with the source’s data_source_id.

​
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 client (Claude connector, Claude Desktop, Cursor, Claude Code, or the hosted platform) and operating system
  • 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: