> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jedify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions for the Jedify MCP integration.

## 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](/mcp/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](/mcp/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](/mcp/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](/mcp/connect#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**:

* [Connect](/mcp/connect) — setup steps
* [Authentication](/mcp/authentication) — sign-in and API keys
* [Asker tools](/mcp/asker/tools-reference) — available analysis tools
* [Asker examples](/mcp/asker/use-cases) — example prompts and workflows