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

# Install MCP

> Set up @hitheo/mcp in Cursor, Claude Code, Warp, Windsurf, VS Code, or any other MCP-compatible IDE.

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

1. **`theo init`** — recommended. Detects every supported IDE on your machine and writes the right config for each in one shot.
2. **`theo mcp install --ide <name>`** — targets a single IDE.
3. **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.

<Note>
  Every method requires the `THEO_API_KEY` environment variable to be set in the shell that launches your IDE. [Get a key](https://api.hitheo.ai) if you don't have one, or run `theo login` to walk through it.
</Note>

## 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:

  ```bash theme={null}
  npm install -g @hitheo/sdk
  ```

## Method 1 — `theo init` (recommended)

`theo init` does the full project bootstrap in one command:

```bash theme={null}
cd your-project
theo init
```

It will:

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

Example output:

```text theme={null}
[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:

```bash theme={null}
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/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:

```json theme={null}
{
  "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.

<Tabs>
  <Tab title="Cursor">
    **Path**: `<project>/.cursor/mcp.json`

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Claude Code">
    **Path**: `<project>/.mcp.json`, or use the CLI helper:

    ```bash theme={null}
    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.
  </Tab>

  <Tab title="Warp">
    **Path**: `<project>/.warp/mcp.json`

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Windsurf">
    **Path**: `~/.codeium/windsurf/mcp_config.json` (user-level, not per-project).

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="VS Code">
    **Path**: `<project>/.vscode/mcp.json`

    ```json theme={null}
    {
      "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.
  </Tab>

  <Tab title="Other IDEs">
    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:

    ```bash theme={null}
    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.
  </Tab>
</Tabs>

## 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](/mcp/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](/mcp/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.