Skip to main content
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:
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:
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}:
    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:
Or pin a specific version in your MCP config:
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:
…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:
  • Or set it explicitly:
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:
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:
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.

​
Large theo_code / theo_complete generations get cut off

Signature: small snippets return fine, but anything app-sized aborts — often at a round number like exceeded 30000ms or Request timed out after ~60s. There are three timeout layers between your agent and the model. @hitheo/mcp 0.3.1+ handles the two it owns:
  • SDK request timeout (was 30s). theo_code and theo_complete now stream instead of making a unary call, so a long-but-active generation runs under an idle (between-token) timeout rather than a total-duration cap. Tune the connect/first-byte budget with THEO_TIMEOUT_MS (default 120000).
  • Server route timeout. Streaming responses return their headers immediately, so the server’s own per-request cap no longer applies to the generation body.
  • Your MCP client’s JSON-RPC request timeout (~60s default). This one lives in your IDE/agent, not in Theo. The server emits notifications/progress heartbeats every 5s while generating, so a client that resets its request timeout on progress stays alive for arbitrarily long generations.
Fix (client side): if very long generations still time out, enable progress-reset and/or raise the request timeout in your MCP client. With the official MCP SDK that’s resetTimeoutOnProgress: true (plus a generous maxTotalTimeout) on the tool call; other clients expose an equivalent “request timeout” setting. A 3-minute app-sized artifact is known to complete once progress-reset is on.

​
theo.config.{js,ts} is being ignored

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