MCP Tools Reference - CostHawk Documentation

Usage Tools

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

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.

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/…”

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”

Codex sync can be disabled globally with COSTHAWK_CODEX_AUTO_SYNC=false.

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`

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

Privacy Tools

What We Send

When syncing local data, CostHawk only uploads usage metadata:

{
  "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.

​Usage Tools

​costhawk_get_usage_summary

​costhawk_get_usage_by_tag

​Savings Tools

​costhawk_get_savings

​costhawk_list_subscriptions

​costhawk_get_savings_breakdown

​Monitoring Tools

​costhawk_detect_anomalies

​costhawk_list_alerts

​Webhook Tools

​costhawk_list_webhooks

​costhawk_create_webhook

​Pricing Tools

​costhawk_get_model_pricing

​Local Sync Tools

​costhawk_sync_claude_code_usage

​costhawk_list_claude_code_sessions

​costhawk_get_local_claude_code_usage

​costhawk_sync_codex_usage

​costhawk_list_codex_sessions

​costhawk_get_local_codex_usage

​Privacy Tools

​What We Send

Usage Tools

costhawk_get_usage_summary

costhawk_get_usage_by_tag

Savings Tools

costhawk_get_savings

costhawk_list_subscriptions

costhawk_get_savings_breakdown

Monitoring Tools

costhawk_detect_anomalies

costhawk_list_alerts

Webhook Tools

costhawk_list_webhooks

costhawk_create_webhook

Pricing Tools

costhawk_get_model_pricing

Local Sync Tools

costhawk_sync_claude_code_usage

costhawk_list_claude_code_sessions

costhawk_get_local_claude_code_usage

costhawk_sync_codex_usage

costhawk_list_codex_sessions

costhawk_get_local_codex_usage

Privacy Tools

What We Send