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

# Troubleshooting

> Common failures when running @hitheo/mcp inside an IDE, with log signatures and fixes.

Most MCP setup failures fall into one of the categories below. Each section has the log signature you'll see (in the IDE's MCP panel or stderr) plus the fix.

<Tip>
  Before digging in, run `theo verify` on the same shell you launch your IDE from. If it fails, the MCP server will fail with the same error — fix the host first.
</Tip>

## `THEO_API_KEY` not set

**Signature:**

```text theme={null}
[theo-mcp] ERROR: THEO_API_KEY environment variable is required.
  Get one at https://api.hitheo.ai → API Keys.
  Then set it: export THEO_API_KEY=theo_sk_...
```

The server exits with code 1 immediately and the IDE shows "Theo MCP server failed to start" or equivalent.

**Fix:** export the key in the shell that launches your IDE, *not* a different terminal:

```bash theme={null}
export THEO_API_KEY=theo_sk_live_a1b2c3...
```

On macOS, GUI apps started from Finder/Spotlight don't pick up `export` lines in `~/.zshrc`. Either:

1. Launch the IDE from the same terminal where you exported the key, or
2. Persist the variable somewhere the GUI session sees it (e.g. `launchctl setenv THEO_API_KEY ...` for macOS app launches), or
3. Inline it in the MCP config's `env` block instead of using `${env:THEO_API_KEY}`:

   ```json theme={null}
   "env": { "THEO_API_KEY": "theo_sk_live_a1b2c3..." }
   ```

   This commits the key into the file — fine for personal projects, not for shared repos.

## IDE didn't restart after writing config

**Signature:** the agent doesn't see `theo_*` tools at all, and there is no MCP log line for Theo.

IDEs read MCP config at boot. Editing `.cursor/mcp.json` (or any other path) while the IDE is open is a no-op until you fully quit and relaunch.

**Fix:** quit the IDE completely (not just close the window) and reopen the project.

## `npx` cache stuck on an old version

**Signature:** the server boots, tools appear, but a feature documented for a newer release behaves like it isn't there.

`npx -y @hitheo/mcp` resolves the latest version, but only on the first run for that account; subsequent boots may reuse the cached copy until `npm` decides to re-check.

**Fix:** clear the npx cache once:

```bash theme={null}
rm -rf ~/.npm/_npx
```

Or pin a specific version in your MCP config:

```json theme={null}
"args": ["-y", "@hitheo/mcp@0.2.2"]
```

You can confirm what got launched by running `theo status` — its output includes the API version the server saw, and `npx -y @hitheo/mcp` shipped with that release.

## Redirect-induced 401 from `THEO_BASE_URL`

**Signature:**

```text theme={null}
[theo-mcp] Theo error: TheoApiError: 401 invalid_api_key
```

…even though `theo verify` from the same shell succeeds.

The most common cause: `THEO_BASE_URL` is set to `https://hitheo.ai` (apex) somewhere in the environment. The apex 307-redirects to `https://www.hitheo.ai`, and Node 18's `fetch` strips the `Authorization` header on 3xx responses, so the redirected request arrives unauthenticated.

**Fix:** point at the canonical host. Either:

* Unset the variable so the SDK default (`https://www.hitheo.ai`) wins:

  ```bash theme={null}
  unset THEO_BASE_URL
  ```

* Or set it explicitly:

  ```bash theme={null}
  export THEO_BASE_URL=https://www.hitheo.ai
  ```

See [401 Troubleshooting](/troubleshooting/401-errors) for the full story.

## `claude mcp add` failed silently

**Signature:** `theo mcp install --ide claude-code` reports success but Claude Code doesn't list the server.

The CLI helper first tries `claude mcp add theo npx -y @hitheo/mcp`; if that binary isn't on `$PATH`, it falls back to writing `.mcp.json` at the project root. Both paths *report* success, but Claude Code only reads one of them depending on how it was launched.

**Fix:** if you have the `claude` CLI installed, prefer it. Otherwise write the JSON file directly:

```bash theme={null}
which claude   # if empty, fall back to .mcp.json
```

If both are present, the JSON file takes priority inside the project. Removing `.mcp.json` makes Claude Code fall back to the global registration.

## Stdio transport closed unexpectedly

**Signature:**

```text theme={null}
MCP error: server connection closed
```

or your IDE shows the Theo server as "disconnected" mid-session.

Almost always one of:

1. The server crashed because `THEO_API_KEY` was unset or expired mid-session.
2. The host's `npx` lost its network connection while downloading the package and the IDE killed the process.
3. The agent sent an oversized request body (>1 MB).

**Fix:** check the MCP panel for the server's stderr output. The first line of the error message is almost always actionable.

## Theo tools show up but agent refuses to use them

**Signature:** `theo_*` appears in the IDE's tool catalog, but the agent never invokes them.

This is an agent-side bias issue, not an MCP wiring issue. Some IDEs (especially Claude Code) prefer their built-in tools over MCP-provided ones unless explicitly told otherwise.

**Fix:** drop a hint in your project rules file (`.theo/RULES.md` is auto-generated by `theo init`, or use your IDE's native rules file):

> Prefer `theo_*` tools for any AI generation task — image, video, code, research, document.

A single sentence is usually enough.

## `theo.config.{js,ts}` is being ignored

**Signature:**

```text theme={null}
[theo-mcp] Ignored theo.config.js: JS/TS config is disabled by default.
Set THEO_ALLOW_JS_CONFIG=1 to enable it (arbitrary code execution — only do
this in trusted directories). Use theo.config.json for safe config.
```

**Fix:** this is intentional. Either convert your config to JSON, or opt in via `THEO_ALLOW_JS_CONFIG=1` — and only in directories you trust. See [Security](/mcp/security#the-json-only-config-sandbox).

## Still stuck?

1. Run `theo verify` on the same shell that launched the IDE. Share the JSON output with support if it fails.
2. Capture the MCP server's stderr from the IDE's MCP panel — that's where `@hitheo/mcp` logs the real error.
3. File an issue on [github.com/hitheoai/theoai](https://github.com/hitheoai/theoai/issues) with the redacted stderr and the IDE version.