Skip to main content

​
Choose Your Integration

CostHawk supports three integration paths. Start with the one that matches your use case.
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}.

Admin API Sync

Recommended start for teams. Paste provider admin keys and get org-level usage/cost visibility with no app code changes.

MCP Server

For Claude Code / Claude Desktop / Codex workflows. Keep MCP enabled for assistant-native queries and local usage operations.

Proxy + Wrapped Keys

Advanced runtime controls: swap your SDK base URL to the CostHawk proxy and use a wrapped key there.
MCP is fully supported and can run alongside Admin API or Proxy integrations.

Not Sure Which Key Goes Where?

Use the Wrapped Keys guide if you are routing provider SDK traffic. Use Authentication if you are configuring MCP or CostHawk API access.

​
Fastest Path: Admin API Sync

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

Create provider admin keys

Generate an Anthropic Admin key (sk-ant-admin-...) and an OpenAI org admin key.
2

Connect in CostHawk

Add both keys in CostHawk Integrations/Connections.
3

Wait for first sync

Usage appears within minutes; provider cost endpoints are daily by design.

Admin API Guide

Full setup details, security model, and sync behavior.

​
MCP Server Setup

​
Prerequisites

  • A CostHawk account (join the waitlist if you don’t have one)
  • Claude Code or Claude Desktop installed
Run: 
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): 
{
  "$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

​
Step 3: Run Self-Test (Required)

Run: 
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:
  • “What’s my AI API usage this month?”
  • “Show me costs broken down by provider”
  • “How many tokens have I used today?”
  • “Am I saving money with Claude Max?”
  • “Show my savings vs retail pricing”
  • “Break down my savings by model”
  • “Are there any cost anomalies I should know about?”
  • “List my unread alerts”
  • “Create a Slack webhook for budget alerts”

Need Explicit Ops Checks?

Use the Operations Runbook for self-test interpretation, auto-sync behavior, and Codex troubleshooting.

​
Alternative: Manual Configuration

If you cannot use browser login, create a token in Settings → Developer and use manual token mode. 
claude mcp add -s user -e COSTHAWK_API_KEY=YOUR_TOKEN_HERE -e COSTHAWK_AUTO_SYNC=true costhawk -- npm exec --yes costhawk@latest
If you prefer to configure manually, add this to your MCP config file:
Edit ~/.claude/.mcp.json:
{
  "mcpServers": {
    "costhawk": {
      "command": "npx",
      "args": ["--yes", "costhawk@latest"],
      "env": {
        "COSTHAWK_API_KEY": "YOUR_TOKEN_HERE",
        "COSTHAWK_AUTO_SYNC": "true"
      }
    }
  }
}

​
Next Steps

API Proxy Setup

Track costs from any app by routing API calls through CostHawk

MCP Tools

Explore all available MCP tools and their parameters

Usage Tracking

Learn about usage tracking and analytics

Alerts & Budgets

Set up spending alerts and budget limits