> ## Documentation Index
> Fetch the complete documentation index at: https://docs.costhawk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the CostHawk MCP server for Claude Code and Claude Desktop

## Quick Setup

### macOS / Linux

Recommended command:

```bash theme={null}
npm exec --yes costhawk@latest -- --login
```

This opens browser approval and writes MCP config automatically.

### Windows

Use the same login flow:

```powershell theme={null}
npm exec --yes costhawk@latest -- --login
```

### What Login Creates

* One hybrid token with scopes: `mcp:read`, `mcp:write`, `otel:ingest`
* Claude MCP config written automatically
* Optional OpenCode config if selected in setup prompts

***

## Verify Installation

After setup, verify it worked:

```bash theme={null}
npm exec --yes costhawk@latest -- --self-test
```

You should see:

* `"hasApiKey": true`
* `"autoSyncEnabled": true` (if you enabled auto-sync)
* `"codexAutoSyncEnabled": true` (unless intentionally disabled)
* `"local.codexDir": true` when Codex sessions are discoverable

Then restart Claude Code and ask:

> "What CostHawk tools are available?"
>
> "List my Codex sessions from the last 7 days"

<Card title="Need Explicit Diagnostics?" icon="list-check" href="/mcp-server/operations">
  Follow the MCP Operations Runbook for self-test interpretation, auto-sync checks, and Codex troubleshooting.
</Card>

***

## Alternative: --setup Command (All Platforms)

If you already have a token and want token mode directly:

```bash theme={null}
npm exec --yes costhawk@latest -- --setup --api-key YOUR_TOKEN_HERE --auto-sync --codex-sync
```

Or configure manually with `claude mcp add`:

```bash theme={null}
claude mcp add -s user -e COSTHAWK_API_KEY=YOUR_TOKEN_HERE -e COSTHAWK_AUTO_SYNC=true costhawk -- npm exec --yes costhawk@latest
```

***

## OpenCode (opencode.ai)

OpenCode reads MCP servers from `~/.config/opencode/opencode.json` (or `opencode.jsonc`). Add CostHawk under `mcp`:

```jsonc theme={null}
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "costhawk": {
      "type": "local",
      "command": ["npx", "--yes", "costhawk@latest"],
      "enabled": true,
      "environment": {
        "COSTHAWK_API_KEY": "YOUR_TOKEN_HERE"
      }
    }
  }
}
```

If you also use Claude Code or the OpenAI Codex CLI on this machine, you can enable local auto-sync by adding
`"COSTHAWK_AUTO_SYNC": "true"` (and optionally `"COSTHAWK_CODEX_AUTO_SYNC": "false"` to disable Codex sync).

Prefer a guided setup? Run:

```bash theme={null}
npm exec --yes costhawk@latest -- --login --opencode --no-claude
```

***

## Claude-Only Mode

If you want to sync Claude Code usage but **not** Codex CLI, add the extra env var:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    claude mcp add -s user \
      -e COSTHAWK_API_KEY=YOUR_TOKEN_HERE \
      -e COSTHAWK_AUTO_SYNC=true \
      -e COSTHAWK_CODEX_AUTO_SYNC=false \
      costhawk -- npm exec --yes costhawk@latest
    ```
  </Tab>

  <Tab title="Windows (manual)">
    ```json theme={null}
    {
      "mcpServers": {
        "costhawk": {
          "command": "npx",
          "args": ["--yes", "costhawk@latest"],
          "env": {
            "COSTHAWK_API_KEY": "YOUR_TOKEN_HERE",
            "COSTHAWK_AUTO_SYNC": "true",
            "COSTHAWK_CODEX_AUTO_SYNC": "false"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

***

## Claude Desktop

### macOS

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "costhawk": {
      "command": "npx",
      "args": ["--yes", "costhawk@latest"],
      "env": {
        "COSTHAWK_API_KEY": "YOUR_TOKEN_HERE",
        "COSTHAWK_AUTO_SYNC": "true"
      }
    }
  }
}
```

### Windows

Edit `%APPDATA%\Claude\claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "costhawk": {
      "command": "npx",
      "args": ["--yes", "costhawk@latest"],
      "env": {
        "COSTHAWK_API_KEY": "YOUR_TOKEN_HERE",
        "COSTHAWK_AUTO_SYNC": "true"
      }
    }
  }
}
```

Then restart Claude Desktop.

***

## Updating

The MCP server uses `costhawk@latest`, which usually refreshes automatically after restart.

To force refresh and verify the binary in use:

```bash theme={null}
npm exec --yes costhawk@latest -- --self-test
```

If needed, clear the npx cache:

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    rm -rf ~/.npm/_npx
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"
    ```
  </Tab>
</Tabs>

Then restart Claude Code/Desktop.

***

## Environment Variables

| Variable                      | Required | Default                          | Description                                                                                                               |
| ----------------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `COSTHAWK_API_KEY`            | Yes      | -                                | Your CostHawk access token                                                                                                |
| `COSTHAWK_API_URL`            | No       | `https://costhawk.ai`            | API base URL                                                                                                              |
| `COSTHAWK_AUTO_SYNC`          | No       | `false`                          | Enable automatic sync on tool calls                                                                                       |
| `COSTHAWK_CODEX_AUTO_SYNC`    | No       | `true` when auto-sync is enabled | Include Codex CLI data in syncs                                                                                           |
| `COSTHAWK_CODEX_SESSIONS_DIR` | No       | auto-discovery                   | Override Codex sessions directory if your setup is non-standard (useful when Codex install or `CODEX_HOME` changes paths) |

***

## Trust & Privacy Features

CostHawk is designed with transparency in mind. Here's how to verify what the MCP server does:

### Preview Mode (Dry Run)

Before syncing any data, you can preview exactly what would be sent:

```
"Sync my Claude Code usage with dryRun enabled"
```

This returns the full payload without making any network requests.

### See What Files We Access

Run this command to see all files CostHawk would read:

```bash theme={null}
npm exec --yes costhawk@latest -- --what-we-read
```

The command output lists detected directories and sample files read for local parsing.

### What Data We Send

When you sync, CostHawk sends only:

* **Token counts** - Input/output/cache tokens per session
* **Model identifiers** - Which AI models were used
* **Timestamps** - When sessions occurred
* **Hashed project IDs** - For grouping (never actual project names or paths)
* **Calculated costs** - Based on token counts and current pricing

We **never** send:

* Your code or files
* Prompt content or conversations
* File paths or project names
* Any personally identifiable information