# Troubleshooting

### "No organization context available"

**Problem:** Tool calls fail with missing organization context.

**Solution:**

1. Ensure you completed the OAuth flow successfully
2. Specify the `organization` parameter explicitly
3. Use `getOrganizationsList` to verify access

### "Token expired"

**Problem:** Access token has expired after 1 hour.

**Solution:** Your MCP client should automatically refresh the token. If not, disconnect and reconnect the server.

### "Shop not found"

**Problem:** During authentication, the specified shop cannot be found.

**Solution:**

1. Verify the shop domain is correct (use format: `mystore.myshopify.com`)
2. Ensure the store has Intelligems installed
3. Check that you have access to the organization

***

### Connection Issues

#### **Problem:** Authorization fails with an `ofid_` reference code.

**Symptoms:**

* Error message: `Authorization with the MCP server failed. You can check your credentials and permissions. If this persists, share this reference with support: 'ofid_<hash>'`
* The OAuth popup completes, but the connector still shows as unauthorized.

**Root Cause:** The browser is holding a stale session tied to a different Intelligems organization (or no active Intelligems session at all), so the OAuth flow resolves against the wrong account context. This is most common for users who have access to multiple stores.

**Solution:**

1. Log out of Intelligems (and Shopify, if you access Intelligems through the Shopify embedded app).
2. Clear cookies and cached site data for `intelligems.io` and `shopify.com` in your browser.
3. Log back into Intelligems, making sure you're in the organization you want the MCP to connect to.
4. Retry the MCP connection and complete the OAuth prompt from the clean session.

If the error persists after a clean re-auth, share the full `ofid_...` reference when contacting support so we can trace the failed OAuth flow.

#### **Problem:** Cannot connect to MCP server.

**Solution:**

1. Verify the server URL is correct: `https://ai.intelligems.io/mcp` or `https://ai.intelligems.io/mcp/sse`
2. Check your internet connection
3. Ensure your MCP client supports HTTP or SSE transport
4. Check MCP client logs for detailed error messages

#### **Problem:** "Server disconnected" - Node.js/npx Not Found (Claude Desktop)

**Symptoms:**

* "Server disconnected" error immediately after installation
* Claude Desktop shows "failed" status for Intelligems MCP server
* Logs show: `Failed to spawn process: No such file or directory`

**Root Cause:** Claude Desktop cannot find the `npx` command. This commonly occurs when:

* Node.js is not installed on your system
* Node.js was installed via a version manager (nvm, Proto, asdf, etc.) that doesn't add executables to standard system paths
* Desktop applications don't inherit your terminal's PATH environment

**Solution:**

**Option 1: Install Node.js via Homebrew (Recommended for macOS)**

```bash
# Install Node.js
brew install node

# Create symlinks so Claude Desktop can find it
sudo ln -sf /opt/homebrew/bin/node /usr/local/bin/node
sudo ln -sf /opt/homebrew/bin/npx /usr/local/bin/npx

# Verify installation
/usr/local/bin/node --version
/usr/local/bin/npx --version
```

**Option 2: Symlink Your Existing Node Installation** If you already have Node.js installed via a version manager:

```bash
# Find your node location
which node
which npx

# Create symlinks (replace paths with your actual node/npx locations)
sudo ln -sf $(which node) /usr/local/bin/node
sudo ln -sf $(which npx) /usr/local/bin/npx

# Verify
/usr/local/bin/node --version
/usr/local/bin/npx --version
```

**After either option:**

1. Completely quit Claude Desktop (Cmd+Q or right-click icon > Quit)
2. Reopen Claude Desktop
3. The Intelligems MCP server should now connect successfully

**For Windows users:** Ensure Node.js is installed from [nodejs.org](https://nodejs.org/) and added to your system PATH during installation.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.intelligems.io/developer-resources/mcp-server/troubleshooting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.