Install MCP - Theo API Docs

You have three ways to install Theo’s MCP server, in increasing order of manual effort:

theo init — recommended. Detects every supported IDE on your machine and writes the right config for each in one shot.
theo mcp install --ide <name> — targets a single IDE.
Hand-written mcp.json — for unusual setups or IDEs we haven’t bundled detection for.

All three install the same package (@hitheo/mcp) and point each IDE at it via npx -y @hitheo/mcp. They differ only in which config files they touch.

Every method requires the THEO_API_KEY environment variable to be set in the shell that launches your IDE. Get a key if you don’t have one, or run theo login to walk through it.

Prerequisites

Node.js 18+ with npx on $PATH (any LTS install will do).
A Theo API key of the form theo_sk_… exported as THEO_API_KEY in your shell.
(optional) The @hitheo/sdk package installed globally for the theo CLI:
```
npm install -g @hitheo/sdk
```

Method 1 — `theo init` (recommended)

theo init does the full project bootstrap in one command:

cd your-project
theo init

It will:

Create theo.config.json (project-level config).
Detect installed IDEs (Cursor, Claude Code, Warp, Windsurf, VS Code).
Write the matching mcp.json for each detected IDE.
Generate .theo/RULES.md so your IDE agent knows the tools exist.

Example output:

[theo] Initializing Theo in this project...
[theo]   ✓ Created theo.config.json
[theo] Detecting IDEs...
[theo]   Found: Cursor, Warp
[theo] Writing MCP configurations...
[theo]   ✓ Cursor: .cursor/mcp.json
[theo]   ✓ Warp: .warp/mcp.json
[theo] Generating agent context...
[theo]   ✓ Created .theo/RULES.md
[theo] ✅ Theo initialized!

Restart each IDE after the command finishes.

Method 2 — `theo mcp install --ide <name>`

Use this when you want MCP set up for a single IDE without touching the others, or to re-run after installing a new IDE:

theo mcp install --ide cursor      # one IDE
theo mcp install --ide all         # every supported IDE
theo mcp install                   # auto-detect installed IDEs

Supported --ide values: cursor, claude-code, warp, windsurf, vscode, all. See the theo mcp install CLI reference for the full flag list.

Method 3 — Hand-written config

Every IDE we support reads a JSON file with an mcpServers.<name> entry. The block is identical across IDEs:

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": { "THEO_API_KEY": "${env:THEO_API_KEY}" }
    }
  }
}

The IDE expands ${env:THEO_API_KEY} to the value from the shell that launched it, so you never commit a key into the repo. Drop the block at the IDE-specific path below.

Path: <project>/.cursor/mcp.json

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": { "THEO_API_KEY": "${env:THEO_API_KEY}" }
    }
  }
}

Cursor picks up the file when you reopen the project. The Theo tools appear under the agent’s tool menu as theo_complete, theo_image, and so on.

Path: <project>/.mcp.json, or use the CLI helper:

claude mcp add theo npx -y @hitheo/mcp

Either approach is fine. The CLI helper writes to the same .mcp.json plus an entry in Claude Code’s per-user store, so it survives across projects.

Path: <project>/.warp/mcp.json

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": { "THEO_API_KEY": "${env:THEO_API_KEY}" }
    }
  }
}

Warp’s agent will list Theo’s tools the next time the project is opened.

Path: ~/.codeium/windsurf/mcp_config.json (user-level, not per-project).

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": { "THEO_API_KEY": "${env:THEO_API_KEY}" }
    }
  }
}

Restart Windsurf — the config is read once at boot.

Path: <project>/.vscode/mcp.json

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": { "THEO_API_KEY": "${env:THEO_API_KEY}" }
    }
  }
}

Requires a VS Code build with MCP support enabled (Insiders or a recent stable release). Reload the window after writing the file.

Any IDE that follows the MCP command / args / env config shape (most do) works with the same block. Drop it wherever that IDE expects MCP server config, set THEO_API_KEY, and restart.If you have to invoke node directly instead of npx, install the package globally and point at the binary:

npm install -g @hitheo/mcp
which theo-mcp   # absolute path; e.g. /usr/local/bin/theo-mcp

Then use "command": "theo-mcp" with an empty args array.

Verify the install

After restarting your IDE, ask the agent something only Theo can answer to confirm the tools are loaded:

“Use the Theo MCP server to run a status check.”

If the agent doesn’t see the tools, see Troubleshooting. The most common cause is a missed restart; the second most common is THEO_API_KEY set in a different shell than the one that launched the IDE.

What gets written where

File	Purpose	Source of truth
`theo.config.json`	Persona, skills, default mode, inline tools	Project Config
`.theo/RULES.md`	Agent-facing description of Theo’s tools	Auto-generated; safe to edit
`.cursor/mcp.json`	Cursor MCP config	Standard MCP block above
`.mcp.json`	Claude Code MCP config	Standard MCP block above
`.warp/mcp.json`	Warp MCP config	Standard MCP block above
`~/.codeium/windsurf/mcp_config.json`	Windsurf user-level MCP config	Standard MCP block above
`.vscode/mcp.json`	VS Code MCP config	Standard MCP block above

theo init is idempotent — re-running it merges into existing files rather than overwriting them.

​Prerequisites

​Method 1 — theo init (recommended)

​Method 2 — theo mcp install --ide <name>

​Method 3 — Hand-written config

​Verify the install

​What gets written where

Prerequisites

Method 1 — `theo init` (recommended)

Method 2 — `theo mcp install --ide <name>`

Method 3 — Hand-written config

Verify the install

What gets written where