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

# MCP Tools Reference

> Complete reference for all CostHawk MCP tools

## Usage Tools

<Note>
  Most tools accept optional `format` (`markdown` or `json`). Write tools that upload data (`costhawk_sync_*`) also accept optional `apiKey` to override `COSTHAWK_API_KEY`.
</Note>

<Info>
  MCP is fully supported. Local sync tools (`costhawk_sync_*`, `costhawk_list_*_sessions`, `costhawk_get_local_*`) remain available and are not being removed in the current release line.
</Info>

### costhawk\_get\_usage\_summary

Get a summary of your AI API usage and costs over a time period.

**Parameters:**

| Parameter   | Type   | Required | Description                                                     |
| ----------- | ------ | -------- | --------------------------------------------------------------- |
| `period`    | string | No       | Preset: `last_24h`, `today`, `yesterday`, `last_7d`, `last_30d` |
| `startDate` | string | No       | Start date (ISO 8601)                                           |
| `endDate`   | string | No       | End date (ISO 8601)                                             |
| `format`    | string | No       | `markdown` (default) or `json`                                  |

**Example:**

> "Show me my API usage for the last 7 days"

***

### costhawk\_get\_usage\_by\_tag

Break down costs by metadata tags like project, environment, or team.

**Parameters:**

| Parameter   | Type   | Required | Description                                      |
| ----------- | ------ | -------- | ------------------------------------------------ |
| `tagKey`    | string | Yes      | Tag to group by (e.g., `project`, `environment`) |
| `startDate` | string | No       | Start date (ISO 8601)                            |
| `endDate`   | string | No       | End date (ISO 8601)                              |
| `limit`     | number | No       | Max results (1-100, default 20)                  |

**Example:**

> "Show me costs broken down by project tag"

***

## Savings Tools

### costhawk\_get\_savings

Show savings vs retail pricing for flat-rate subscriptions like Claude Max or OpenAI Pro.

**Parameters:**

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `period`  | string | No       | `daily`, `weekly`, or `monthly` |
| `date`    | string | No       | Anchor date (ISO 8601)          |

**Example:**

> "Am I saving money with Claude Max this month?"

***

### costhawk\_list\_subscriptions

List your active flat-rate subscriptions.

**Example:**

> "What subscriptions do I have configured?"

***

### costhawk\_get\_savings\_breakdown

Get per-model usage and retail cost breakdown.

**Parameters:**

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `period`  | string | No       | `daily`, `weekly`, or `monthly` |
| `date`    | string | No       | Anchor date (ISO 8601)          |

**Example:**

> "Break down my savings by model"

***

## Monitoring Tools

### costhawk\_detect\_anomalies

Find cost spikes and unusual activity patterns.

**Example:**

> "Are there any cost anomalies I should know about?"

***

### costhawk\_list\_alerts

View recent alerts including budget warnings, cost spikes, and anomaly notifications.

**Parameters:**

| Parameter    | Type    | Required | Description                    |
| ------------ | ------- | -------- | ------------------------------ |
| `limit`      | number  | No       | Max alerts (1-100, default 20) |
| `unreadOnly` | boolean | No       | Show only unread alerts        |

**Example:**

> "Show me my unread alerts"

***

## Webhook Tools

### costhawk\_list\_webhooks

List all configured webhooks for receiving cost alerts.

**Example:**

> "What webhooks do I have set up?"

***

### costhawk\_create\_webhook

Create a new webhook to receive notifications.

**Parameters:**

| Parameter | Type   | Required | Description                                           |
| --------- | ------ | -------- | ----------------------------------------------------- |
| `name`    | string | Yes      | Webhook name                                          |
| `url`     | string | Yes      | Webhook URL                                           |
| `type`    | string | Yes      | `slack`, `discord`, `teams`, `pagerduty`, or `custom` |
| `events`  | array  | Yes      | Events: `cost_spike`, `budget_alert`, `anomaly`, etc. |

**Example:**

> "Create a Slack webhook for budget alerts at [https://hooks.slack.com/](https://hooks.slack.com/)..."

***

## Pricing Tools

### costhawk\_get\_model\_pricing

Look up current pricing for AI models.

**Parameters:**

| Parameter  | Type   | Required | Description                                               |
| ---------- | ------ | -------- | --------------------------------------------------------- |
| `provider` | string | No       | Filter by provider: `openai`, `anthropic`, `google`, etc. |

**Example:**

> "What's the current pricing for Claude Opus?"

***

## Local Sync Tools

### costhawk\_sync\_claude\_code\_usage

Sync Claude Code usage from local transcript files and upload usage metadata to CostHawk.

**Parameters:**

| Parameter         | Type    | Required | Description                                                        |
| ----------------- | ------- | -------- | ------------------------------------------------------------------ |
| `maxAgeHours`     | number  | No       | Only include sessions modified in the last N hours (default `720`) |
| `dryRun`          | boolean | No       | Preview payload without uploading                                  |
| `previewLimit`    | number  | No       | Number of sessions in dry-run preview (default `3`)                |
| `includeFileList` | boolean | No       | Include local file paths read by parser                            |
| `format`          | string  | No       | `markdown` (default) or `json`                                     |

**Example:**

> "Sync my Claude Code usage"

**With dry run:**

> "Preview my Claude Code sync payload"

***

### costhawk\_list\_claude\_code\_sessions

List Claude Code sessions discovered locally before syncing.

**Parameters:**

| Parameter     | Type   | Required | Description                                                        |
| ------------- | ------ | -------- | ------------------------------------------------------------------ |
| `maxAgeHours` | number | No       | Only include sessions modified in the last N hours (default `168`) |
| `limit`       | number | No       | Maximum sessions to return (default `20`)                          |
| `format`      | string | No       | `markdown` (default) or `json`                                     |

***

### costhawk\_get\_local\_claude\_code\_usage

Compute Claude Code usage locally without uploading anything.

**Parameters:**

| Parameter          | Type   | Required | Description                                                       |
| ------------------ | ------ | -------- | ----------------------------------------------------------------- |
| `maxAgeHours`      | number | No       | Only include sessions modified in the last N hours (default `24`) |
| `subscriptionPlan` | string | No       | `pro`, `max_5x`, or `max_20x` (adds local savings estimate)       |
| `format`           | string | No       | `markdown` (default) or `json`                                    |

***

### costhawk\_sync\_codex\_usage

Sync OpenAI Codex CLI usage from local session logs and upload usage metadata to CostHawk.

**Parameters:**

| Parameter         | Type    | Required | Description                                                        |
| ----------------- | ------- | -------- | ------------------------------------------------------------------ |
| `maxAgeHours`     | number  | No       | Only include sessions modified in the last N hours (default `720`) |
| `dryRun`          | boolean | No       | Preview payload without uploading                                  |
| `previewLimit`    | number  | No       | Number of sessions in dry-run preview (default `3`)                |
| `includeFileList` | boolean | No       | Include local file paths read by parser                            |
| `format`          | string  | No       | `markdown` (default) or `json`                                     |

**Example:**

> "Sync my Codex usage"

<Note>
  Codex sync can be disabled globally with `COSTHAWK_CODEX_AUTO_SYNC=false`.
</Note>

***

### costhawk\_list\_codex\_sessions

List Codex sessions discovered locally before syncing.

**Parameters:**

| Parameter     | Type   | Required | Description                                                        |
| ------------- | ------ | -------- | ------------------------------------------------------------------ |
| `maxAgeHours` | number | No       | Only include sessions modified in the last N hours (default `168`) |
| `limit`       | number | No       | Maximum sessions to return (default `20`)                          |
| `format`      | string | No       | `markdown` (default) or `json`                                     |

***

### costhawk\_get\_local\_codex\_usage

Compute Codex usage locally without uploading anything.

**Parameters:**

| Parameter     | Type   | Required | Description                                                       |
| ------------- | ------ | -------- | ----------------------------------------------------------------- |
| `maxAgeHours` | number | No       | Only include sessions modified in the last N hours (default `24`) |
| `format`      | string | No       | `markdown` (default) or `json`                                    |

<Tip>
  If Codex files are in a non-standard directory, set `COSTHAWK_CODEX_SESSIONS_DIR` in MCP env and restart your MCP host.
</Tip>

***

## Privacy Tools

### What We Send

When syncing local data, CostHawk only uploads usage metadata:

```json theme={null}
{
  "sessions": [
    {
      "sessionId": "hashed_abc123",
      "projectId": "hashed_project_id",
      "model": "claude-3-5-sonnet-20241022",
      "inputTokens": 15420,
      "outputTokens": 8230,
      "cacheReadTokens": 5000,
      "cacheCreationTokens": 1200,
      "timestamp": "2025-02-03T10:30:00Z"
    }
  ]
}
```

No code, prompts, file paths, or project names are ever sent.