MCP Server Overview - CostHawk Documentation

The CostHawk MCP (Model Context Protocol) server enables AI assistants like Claude to query your cost data directly from the command line. No need to switch to a browser - just ask Claude about your API spending.

What is MCP?

Model Context Protocol (MCP) is a standard for connecting AI assistants to external tools and data sources. CostHawk’s MCP server lets Claude:

Check your API usage and costs
Analyze savings from flat-rate subscriptions
Sync Claude Code and Codex CLI usage data
Detect cost anomalies
Manage webhooks and alerts
Look up model pricing

Trust & Privacy

CostHawk was built for developers who care about transparency. We believe you should know exactly what runs on your machine.

Local-First Parsing

We compute usage locally from Claude/Codex session files before anything leaves your machine.

No Prompt Content

Only usage metadata is sent: token counts, models, timestamps, and hashed project IDs — never your code or prompts.

Preview Before Upload

Use dryRun: true to see exactly what would be sent, with payload previews for full transparency.

Opt-In Auto-Sync

Automatic uploads are off by default. Enable with COSTHAWK_AUTO_SYNC=true and disable Codex sync anytime.

See What We Read

Run this command to see exactly which files CostHawk accesses:

npm exec --yes costhawk@latest -- --what-we-read

This prints all file paths the MCP server would access without making any network requests.

Installation

macOS/Linux
Windows

npm exec --yes costhawk@latest -- --login

npm exec --yes costhawk@latest -- --login

The login flow handles approval + setup automatically.

Default login token is hybrid (mcp:read, mcp:write, otel:ingest), so it also works for optional OTel ingestion. After installation, restart Claude Code to load the MCP server.

Full Installation Guide

See manual configuration, Claude Desktop setup, and troubleshooting.

Available Tools

Tool	Description
`costhawk_get_usage_summary`	Get usage and cost summary for a date range
`costhawk_get_usage_by_tag`	Break down costs by metadata tags
`costhawk_detect_anomalies`	Find cost spikes and unusual patterns
`costhawk_list_webhooks`	List configured alert webhooks
`costhawk_create_webhook`	Set up new webhooks
`costhawk_get_model_pricing`	Look up model pricing by provider
`costhawk_list_alerts`	View alerts and notifications
`costhawk_get_savings`	Show savings vs retail pricing
`costhawk_list_subscriptions`	List active subscriptions
`costhawk_get_savings_breakdown`	Per-model usage breakdown
`costhawk_sync_claude_code_usage`	Sync Claude Code usage from local files
`costhawk_sync_codex_usage`	Sync OpenAI Codex CLI usage from local files

Full Tool Reference

See detailed documentation for each tool including parameters and examples.

Operations Runbook

Explicit checks for self-test, auto-sync, and Codex session troubleshooting.

Example Conversations

Check your usage:

“What’s my AI API usage this month?”

Analyze savings:

“Am I saving money with my Claude Max subscription?”

Monitor costs:

“Are there any cost anomalies I should know about?”

Set up alerts:

“Create a Slack webhook for budget alerts”

Requirements

Node.js 18+
Claude Code or Claude Desktop
A CostHawk account with an access token

Troubleshooting

Tool not found errors

Ensure Claude was restarted after adding the MCP server
Verify the config file syntax is valid JSON
Check that the server name is costhawk

Authentication failed

Verify your access token is correct
Check the token is active in your CostHawk dashboard
Make sure you’ve been approved from the waitlist

Connection refused

Ensure you have internet connectivity
Check if costhawk.ai is accessible
Verify no firewall is blocking the connection

MCP Server

​What is MCP?

​Trust & Privacy