Skip to main content

​
Quick Setup

​
macOS / Linux

Recommended command: 
npm exec --yes costhawk@latest -- --login
This opens browser approval and writes MCP config automatically.

​
Windows

Use the same login flow: 
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: 
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”

Need Explicit Diagnostics?

Follow the MCP Operations Runbook for self-test interpretation, auto-sync checks, and Codex troubleshooting.

​
Alternative: —setup Command (All Platforms)

If you already have a token and want token mode directly: 
npm exec --yes costhawk@latest -- --setup --api-key YOUR_TOKEN_HERE --auto-sync --codex-sync
Or configure manually with claude mcp add: 
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: 
{
  "$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: 
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: 
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

​
Claude Desktop

​
macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json: 
{
  "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: 
{
  "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: 
npm exec --yes costhawk@latest -- --self-test
If needed, clear the npx cache: 
rm -rf ~/.npm/_npx
Then restart Claude Code/Desktop.

​
Environment Variables

VariableRequiredDefaultDescription
COSTHAWK_API_KEYYes-Your CostHawk access token
COSTHAWK_API_URLNohttps://costhawk.aiAPI base URL
COSTHAWK_AUTO_SYNCNofalseEnable automatic sync on tool calls
COSTHAWK_CODEX_AUTO_SYNCNotrue when auto-sync is enabledInclude Codex CLI data in syncs
COSTHAWK_CODEX_SESSIONS_DIRNoauto-discoveryOverride 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: 
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