Skip to main content

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.

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

​
THEO_API_KEY not set

Signature: 
[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: 
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}: 
    "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: 
rm -rf ~/.npm/_npx
Or pin a specific version in your MCP config: 
"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: 
[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: 
    unset THEO_BASE_URL
  • Or set it explicitly: 
    export THEO_BASE_URL=https://www.hitheo.ai
See 401 Troubleshooting 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: 
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: 
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: 
[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.

​
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 with the redacted stderr and the IDE version.