> For the complete documentation index, see [llms.txt](https://docs.intelligems.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.intelligems.io/developer-resources/mcp-server/troubleshooting.md).

# 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.

***

#### Checkout Blocks

**Problem: A checkout block test built through the MCP doesn't appear at checkout.**

**Symptoms:**

* The test looks correctly configured in Intelligems — `list_checkout_blocks` returns the blocks and their display conditions.
* `get_experience` returns `hasTestCheckoutBlocks: true`.
* Nothing renders at checkout, with no error anywhere.

**Root Cause:** The block hasn't been placed in your Shopify checkout. Shopify doesn't let apps add checkout blocks programmatically, so the MCP can create and configure a block but can't place it. Until someone adds it in the Shopify checkout editor, there's no slot for it to render into.

**Solution:**

1. Run `list_checkout_blocks` and note each block's Location ID.
2. In Shopify Admin, go to **Settings** → **Checkout**, and click **Customize** under Configurations.
3. In the top panel click **Apps**, navigate to **Intelligems**, click (+), and choose Checkout.
4. Paste the Location ID into the block settings, exactly as it appears in Intelligems.
5. Toggle on **Include block in Shop Pay** (recommended).
6. Drag the block into position and click **Save**.

This requires Shopify checkout permissions. If your account can't open Settings → Checkout, someone on the store's side has to do it.

A Location ID that doesn't match fails silently — you won't see an error in Intelligems or in Shopify. If the block still doesn't render, check the two IDs character for character before looking anywhere else.

Also confirm the test has been started. A correctly placed, correctly matched block renders nothing while the experience is in draft.

**Problem: More than one block renders, or the wrong one does.**

**Root Cause:** Every block evaluates its display conditions independently, and every block whose conditions match will render. There's no priority ordering or first-match-wins.

**Solution:** Make the conditions mutually exclusive. Give each lower-ranked block a `doesNotInclude` clause for everything ranked above it, so only one set of conditions can ever be true at once.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.