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

# Quickstart

> Get up and running with CostHawk in 5 minutes

## Choose Your Integration

CostHawk supports three integration paths. Start with the one that matches your use case.

<Warning>
  CostHawk has two different credentials that can both look like `ch_sk_...`.
  Use access tokens for MCP / OTel / CostHawk API auth.
  Use wrapped keys only with `https://costhawk.ai/api/proxy/{provider}`.
</Warning>

<CardGroup cols={3}>
  <Card title="Admin API Sync" icon="key" href="/integrations/admin-api">
    **Recommended start** for teams. Paste provider admin keys and get org-level usage/cost visibility with no app code changes.
  </Card>

  <Card title="MCP Server" icon="robot" href="#mcp-server-setup">
    For **Claude Code / Claude Desktop / Codex workflows**. Keep MCP enabled for assistant-native queries and local usage operations.
  </Card>

  <Card title="Proxy + Wrapped Keys" icon="shuffle" href="/integrations/wrapped-keys">
    Advanced runtime controls: swap your SDK base URL to the CostHawk proxy and use a wrapped key there.
  </Card>
</CardGroup>

<Info>
  MCP is fully supported and can run alongside Admin API or Proxy integrations.
</Info>

<Card title="Not Sure Which Key Goes Where?" icon="key" href="/integrations/wrapped-keys">
  Use the Wrapped Keys guide if you are routing provider SDK traffic. Use Authentication if you are configuring MCP or CostHawk API access.
</Card>

***

## Fastest Path: Admin API Sync

If you want visibility quickly, connect provider admin keys first:

<Steps>
  <Step title="Create provider admin keys">
    Generate an Anthropic Admin key (`sk-ant-admin-...`) and an OpenAI org admin key.
  </Step>

  <Step title="Connect in CostHawk">
    Add both keys in CostHawk Integrations/Connections.
  </Step>

  <Step title="Wait for first sync">
    Usage appears within minutes; provider cost endpoints are daily by design.
  </Step>
</Steps>

<Card title="Admin API Guide" icon="key" href="/integrations/admin-api">
  Full setup details, security model, and sync behavior.
</Card>

***

## MCP Server Setup

### Prerequisites

* A CostHawk account (join the [waitlist](https://costhawk.ai) if you don't have one)
* Claude Code or Claude Desktop installed

## Step 1: Browser Login (Recommended)

Run:

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

This opens your browser, asks you to approve login, then writes MCP config automatically.
Default login token scopes are:

* `mcp:read`
* `mcp:write`
* `otel:ingest` (same token can be reused for optional OTel)

## Step 2: Restart Claude Code

After login/setup, restart Claude Code so new tools load.

### OpenCode (opencode.ai)

Add CostHawk to your OpenCode config at `~/.config/opencode/opencode.json` (or `opencode.jsonc`):

```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
```

## Step 3: Run Self-Test (Required)

Run:

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

Confirm:

* `"hasApiKey": true`
* `"autoSyncEnabled": true` if you want automatic uploads
* `"codexAutoSyncEnabled": true` if you want Codex included in auto-sync
* `"local.codexDir": true` if Codex sessions are discoverable on this machine

If `local.codexDir` is `false` and you use a custom Codex path, set `COSTHAWK_CODEX_SESSIONS_DIR` in MCP env.

## Step 4: Start Using CostHawk

You can now ask Claude about your API costs:

<AccordionGroup>
  <Accordion title="Usage Queries">
    * "What's my AI API usage this month?"
    * "Show me costs broken down by provider"
    * "How many tokens have I used today?"
  </Accordion>

  <Accordion title="Savings Analysis">
    * "Am I saving money with Claude Max?"
    * "Show my savings vs retail pricing"
    * "Break down my savings by model"
  </Accordion>

  <Accordion title="Alerts & Monitoring">
    * "Are there any cost anomalies I should know about?"
    * "List my unread alerts"
    * "Create a Slack webhook for budget alerts"
  </Accordion>
</AccordionGroup>

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

## Alternative: Manual Configuration

If you cannot use browser login, create a token in **Settings → Developer** and use manual token mode.

<CodeGroup>
  ```bash Global (All Projects) 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
  ```

  ```bash Current Project Only theme={null}
  claude mcp add -e COSTHAWK_API_KEY=YOUR_TOKEN_HERE -e COSTHAWK_AUTO_SYNC=true costhawk -- npm exec --yes costhawk@latest
  ```
</CodeGroup>

If you prefer to configure manually, add this to your MCP config file:

<Tabs>
  <Tab title="Claude Code">
    Edit `~/.claude/.mcp.json`:

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

  <Tab title="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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop (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"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Proxy Setup" icon="shuffle" href="/integrations/overview">
    Track costs from any app by routing API calls through CostHawk
  </Card>

  <Card title="MCP Tools" icon="wrench" href="/mcp-server/tools">
    Explore all available MCP tools and their parameters
  </Card>

  <Card title="Usage Tracking" icon="chart-line" href="/features/usage-tracking">
    Learn about usage tracking and analytics
  </Card>

  <Card title="Alerts & Budgets" icon="bell" href="/features/alerts">
    Set up spending alerts and budget limits
  </Card>
</CardGroup>