> ## 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 the SDK

> Set up @hitheo/sdk for TypeScript and Node.js projects.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @hitheo/sdk
  ```

  ```bash yarn theme={null}
  yarn add @hitheo/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @hitheo/sdk
  ```
</CodeGroup>

**Requirements:** Node.js 18+ with native `fetch` support.

## Initialize the Client

```typescript theme={null}
import { Theo } from "@hitheo/sdk";

const theo = new Theo({
  apiKey: process.env.THEO_API_KEY!,
  // Optional:
  // baseUrl: "https://www.hitheo.ai",   // default (canonical `www` host)
  // timeoutMs: 30_000,                  // default
  // maxRetries: 2,                      // default — retries on 429/5xx
});
```

## Configuration Options

| Option       | Type     | Default                 | Description                                                                                                           |
| ------------ | -------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `apiKey`     | `string` | **required**            | Your `theo_sk_...` API key                                                                                            |
| `baseUrl`    | `string` | `https://www.hitheo.ai` | API base URL (always target `www` — the apex redirects and some HTTP clients strip the `Authorization` header on 3xx) |
| `timeoutMs`  | `number` | `30000`                 | Request timeout in milliseconds                                                                                       |
| `maxRetries` | `number` | `2`                     | Max retry attempts on 429/5xx errors                                                                                  |

## Retry Behavior

The SDK automatically retries on:

* **429 Too Many Requests** — respects the `Retry-After` header
* **5xx Server Errors** — exponential backoff (1s, 2s, 4s, max 8s)

Client errors (400, 401, 403, 404) are not retried.

## Also Available

### CLI

The SDK includes a CLI for terminal usage:

```bash theme={null}
npm install -g @hitheo/sdk
theo init        # Set up Theo in a project
theo status      # Check connection + health (probes both apex and www)
theo verify      # Machine-readable JSON diagnostic (CI-friendly)
theo complete "What is quantum computing?"
```

See the [CLI Reference](/cli-reference/overview) for all commands.

### MCP Server — IDE Integration

Use Theo inside Cursor, Claude Code, Warp, Windsurf, and VS Code via MCP:

First, set your API key as an environment variable:

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

Then pick your IDE:

<Tabs>
  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project root:

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

    Or run:

    ```bash theme={null}
    theo mcp install --ide cursor
    ```
  </Tab>

  <Tab title="Claude Code">
    Run this in your terminal:

    ```bash theme={null}
    claude mcp add theo npx -y @hitheo/mcp
    ```

    Or run:

    ```bash theme={null}
    theo mcp install --ide claude-code
    ```
  </Tab>

  <Tab title="Warp">
    Add to `.warp/mcp.json` in your project root:

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

    Or run:

    ```bash theme={null}
    theo mcp install --ide warp
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to `~/.codeium/windsurf/mcp_config.json`:

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

    Or run:

    ```bash theme={null}
    theo mcp install --ide windsurf
    ```
  </Tab>

  <Tab title="VS Code">
    Add to `.vscode/mcp.json` in your project root:

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

    Or run:

    ```bash theme={null}
    theo mcp install --ide vscode
    ```
  </Tab>

  <Tab title="All IDEs">
    Auto-detect and configure all installed IDEs at once:

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

    This detects Cursor, Claude Code, Warp, Windsurf, and VS Code, writes the correct config for each, and creates a `theo.config.json` for project-level settings.
  </Tab>
</Tabs>

Restart your IDE after adding the config.