# MCP server

The Costfluent MCP server lets an AI assistant answer questions about your cloud spend without you opening the app. It runs on your machine, speaks the Model Context Protocol to the assistant over stdin and stdout, and calls the Public API with an API token you give it. It only reads: no tool creates, changes or deletes anything.

## Before you start

<PlanAvailability feature="ApiTokens" plan="Starter" />

- Creating the token needs the Owner, Integration Owner or Editor organization role; see [API authentication](/api/authentication).
- The assistant must support local MCP servers that run as a command, as Claude Code, Claude Desktop and Cursor do.

## Create a token

<Stepper>

1. Open **Settings**, then **API tokens**, and select **Create API token**.
2. Enter a **Name** that says which assistant uses the token, such as `Claude Code on my laptop`.
3. Under **Access**, choose the workspace the assistant works in, so the token reaches nothing else. Keep **Whole organization** only when the assistant compares workspaces.
4. Under **Start from**, choose **Read only**. Clear any capability the assistant does not need: the tools need **View workspaces**, **View costs**, **View cost reports**, **View budgets** and **View anomalies**.
5. Choose an **Expiration**, such as 90 days, and select **Create API token**.
6. Copy the token from **Your API token**. It is shown only once.

</Stepper>

:::caution
The token is stored in your assistant's configuration file, in plain text. Give it only read capabilities and an expiration, and revoke it under **API tokens** when you stop using the assistant.
:::

## Install the server

Download the archive for your platform from the [latest release](https://github.com/costfluent/costfluent-mcp/releases/latest) and put `costfluent-mcp` on your `PATH`, or build it with Go:

```bash
go install github.com/costfluent/costfluent-mcp/cmd/costfluent-mcp@latest
```

Each release carries a build provenance attestation, which `gh attestation verify <archive> --repo costfluent/costfluent-mcp` checks.

## Connect your assistant

The server reads `COSTFLUENT_API_TOKEN`, the token, and optionally `COSTFLUENT_BASE_URL`, which defaults to `https://api.costfluent.com` and must use https.

<Stepper>

1. In Claude Code, run `claude mcp add costfluent --env COSTFLUENT_API_TOKEN=<token> -- costfluent-mcp`.
2. In Claude Desktop, Cursor or another client with an `mcpServers` file, add the server as below.
3. Restart the assistant and ask it a question, such as "What did we spend on AWS last month, by service?".

</Stepper>

```json
{
  "mcpServers": {
    "costfluent": {
      "command": "costfluent-mcp",
      "env": { "COSTFLUENT_API_TOKEN": "<token>" }
    }
  }
}
```

## Tools

| Tool | What it reads | Capability |
|---|---|---|
| `list_workspaces` | The workspaces the token can read | **View workspaces** |
| `query_costs` | Cost, usage or resource count over a date range, per day, week, month or quarter, grouped by up to three dimensions and narrowed by a cost filter | **View costs** |
| `list_cost_reports` | A workspace's saved cost reports | **View cost reports** |
| `get_cost_report_data` | The numbers a saved report shows now | **View costs** |
| `list_budgets` | Budgets with their current spend and state | **View budgets** |
| `list_anomalies` | Detected cost anomalies, newest first | **View anomalies** |

## How it behaves

- At start the server asks the API which capabilities its token carries, and offers the assistant only the tools those capabilities allow. A token the API refuses stops the server with the API's error.
- Workspace tools need a `workspace_id` with an organization token; the assistant finds the IDs with `list_workspaces`. A workspace token reads its own workspace unless told otherwise, and the API refuses any other.
- When the API refuses a call, the assistant receives the API's error with its status, code and detail, and can explain it or adjust the question.
- Every call counts against the token's request limit. The server waits out a short limit and returns a longer one to the assistant.
- The server never writes the token to its log or to a tool result; it travels only in the request header.

## Related

- [API authentication](/api/authentication)
- [Terraform](/developers/terraform)
- [API reference](/api)