> ## 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 Server Overview

> Query your CostHawk data directly from Claude Code - with privacy-first design

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.

<CardGroup cols={2}>
  <Card title="Local-First Parsing" icon="shield">
    We compute usage locally from Claude/Codex session files before anything leaves your machine.
  </Card>

  <Card title="No Prompt Content" icon="eye-slash">
    Only usage metadata is sent: token counts, models, timestamps, and hashed project IDs — never your code or prompts.
  </Card>

  <Card title="Preview Before Upload" icon="file-lines">
    Use `dryRun: true` to see exactly what would be sent, with payload previews for full transparency.
  </Card>

  <Card title="Opt-In Auto-Sync" icon="toggle-off">
    Automatic uploads are off by default. Enable with `COSTHAWK_AUTO_SYNC=true` and disable Codex sync anytime.
  </Card>
</CardGroup>

### See What We Read

Run this command to see exactly which files CostHawk accesses:

```bash theme={null}
npm exec --yes costhawk@latest -- --what-we-read
```

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

## Installation

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    npm exec --yes costhawk@latest -- --login
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    npm exec --yes costhawk@latest -- --login
    ```

    The login flow handles approval + setup automatically.
  </Tab>
</Tabs>

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.

<Card title="Full Installation Guide" icon="book" href="/mcp-server/installation">
  See manual configuration, Claude Desktop setup, and troubleshooting.
</Card>

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

<Card title="Full Tool Reference" icon="wrench" href="/mcp-server/tools">
  See detailed documentation for each tool including parameters and examples.
</Card>

<Card title="Operations Runbook" icon="list-check" href="/mcp-server/operations">
  Explicit checks for self-test, auto-sync, and Codex session troubleshooting.
</Card>

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

<AccordionGroup>
  <Accordion title="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`
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Connection refused">
    * Ensure you have internet connectivity
    * Check if costhawk.ai is accessible
    * Verify no firewall is blocking the connection
  </Accordion>
</AccordionGroup>