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

# MCP troubleshooting

> Diagnose and fix common MCP server connection, authentication, and tool errors.

Find the symptom that matches your problem. Each entry names the likely cause and the fix.

## Claude Code troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| Browser doesn't open. | Auto-launch failed. | Copy the URL from the terminal and open it manually. |
| Connection refused on port 35535. | Port is in use. | Run `lsof -i :35535` on macOS or Linux, or `netstat -ano \| findstr :35535` on Windows, stop the process, and retry. |
| Failed to connect after OAuth. | Token didn't persist. | Re-run the [Step 2 command](https://docs.kameleoon.com/mcp/set-up-clients.md#step-2-complete-oauth-authentication) to refresh your token. |
| Tools aren't visible in Claude. | Session started before adding the server. | Start a new Claude Code conversation. |
| A newer tool, such as `experiment_update` or `trigger_list`, is missing from the tool list. | The client keeps the tool list it loaded before Kameleoon released these tools. | Reconnect the server. In Claude.ai, go to **Customize** > **Connectors** and reconnect Kameleoon. In Claude Code, run `/mcp` and choose **Reconnect**. |
| `mcpServers` key rejected in `settings.json`. | Wrong file; Claude Code doesn't use that key. | Use the `claude mcp add` command instead. |
| Auth error after a long period. | OAuth token expired. | Re-run the [Step 2 command](https://docs.kameleoon.com/mcp/set-up-clients.md#step-2-complete-oauth-authentication). |

## General troubleshooting

### Rate-limit error

A tool call returns a rate-limit error that includes a `retryAfterSeconds` value.

* **Cause:** The call went over the MCP server's per-tool limit for your user, or the Automation API gateway limit for the MCP integration.
* **Fix:** Wait the number of seconds in `retryAfterSeconds`, then retry the call. For bulk work, batch your requests or throttle the loop so it stays under the limits.

### Port 35535 is already in use

If authentication fails with an `EADDRINUSE` error, another process already listens on the OAuth callback port.

* **Cause:** A stale `mcp-remote` process remains active from a previous authentication attempt.
* **Fix:** Stop the stale process that's using port 35535, then rerun the OAuth command.

### MCP server doesn't appear in Codex chat

Codex might not hot-reload newly added MCP servers into an already-running thread.

* **Fix:** Refresh Codex or start a new session after you update `config.toml`.

### Browser flow doesn't complete

If the OAuth browser window opens but authorization doesn't finish:

* Confirm that you clicked the **Authorize** button on the Kameleoon login page.
* Check that your browser or system settings don't block `localhost` callbacks.
* Manually open the callback URL if your browser fails to launch it automatically.

### A tool returns BLOCKED instead of making the change

Tools that change live traffic return a preview with the status `BLOCKED` until you confirm, which doesn't mean an error.

* **Fix:** Read the preview, and if the change is what you want, ask your AI assistant to repeat the call with `confirm` set to `true`. For `segment_delete` and `trigger_delete`, use `force` instead.

### Health check returns DOWNSTREAM\_ERROR

`experiment_health_check_get` fails for an experiment that uses a ratio goal whose numerator goal isn't attached to the experiment.

* **Fix:** Attach the missing goal in the app, or run the check on another experiment.

### Goal impacts return no rows

`goal_experiment_impacts_list` can return no rows while the data is still preparing.

* **Fix:** Check the `readiness` field (`PREPARING` or `PARTIAL`), and ask again after `retryAfterSeconds`.

### Single-day results differ from the daily breakdown

A one-day window follows your organization's time zone. Daily buckets follow the site's time zone, so the two can cover different 24 hours.

### Improvement is 0 or missing on a variation

There's no baseline to compare with when the original gets 0% of the traffic.

### A page, page size, or limit of 0 returns the default

In `takeaway_list` and `goal_experiment_impacts_list`, 0 for a page, page size, or limit means "use the default."

### New tools are missing after a release

Clients keep the old tool list until you reconnect.

* **Fix:** After a release, reconnect the Kameleoon MCP connector.

### Headless or remote agents fail to authenticate

Remote or headless agents (such as cloud-hosted Codex) can't complete the browser-based authorization step.

* **Fix:** Use a desktop version of your tool instead.

### Package runner command not found

If the command fails with a "not found" error, ensure that `npx` is available on your system path. Node.js versions 8.2 and later include `npx` by default.