Copy page

Developers

Command line

Run every Costfluent MCP tool from a terminal, a script or a CI job with the costfluent command, check a token with costfluent whoami, sign in with costfluent login instead of a token, post a Terraform pull request's cost estimate from any CI, and connect Claude Code, Cursor, Codex, VS Code or Copilot CLI to the MCP server.

The costfluent command runs each tool of the MCP server from a terminal, a script or a CI job. A command is the tool's name with hyphens and takes the tool's arguments as flags, so it reads exactly what the tool reads, with the same capability check, validation and result. It prints JSON for a script and a table for you. A read tool's command only reads; a write tool's command creates or changes what the tool does, and only once an Owner lets AI agents create and change objects (the MCP page says how). No command deletes anything in Costfluent or touches your cloud. costfluent estimate, described below, posts a Terraform pull request's cost estimate from any CI.

Before you start

Included in the Pro, Business and Custom plans. Compare plans

• An API token. Create one as the MCP guide's Create a token describes, from the Read only preset; a CI job takes its own token. On your own computer you can sign in instead.
• A macOS, Linux or Windows machine, amd64 or arm64.

Install

Download the archive for your platform from the latest release and put costfluent on your PATH. The archive holds both costfluent and the MCP server, costfluent-mcp. Or build them with Go:

Code
go install github.com/costfluent/costfluent-mcp/cmd/costfluent@latest
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.

Run a command

Code
export COSTFLUENT_API_TOKEN=<token>
costfluent whoami
costfluent query-costs --start-date 2026-10-01 --end-date 2026-10-31 --group-by ServiceName
costfluent list-budgets --output json | jq '.items[] | select(.state == "over")'

Sign in

Instead of a token, costfluent login signs you in through your browser, where you approve read access for one organization, as Sign in from an app describes. Commands then run without COSTFLUENT_API_TOKEN; a token that is set still wins. costfluent logout revokes the sign-in and forgets it on this computer, also when the revocation cannot reach Costfluent.

Code
costfluent login
costfluent whoami
costfluent logout

• The sign-in is kept in the operating system's credential store: the macOS Keychain, the Secret Service on Linux or the Windows Credential Manager. On a computer without one, costfluent login --insecure-storage keeps it in costfluent/credentials.json under XDG_CONFIG_HOME, or the system's configuration directory, readable by you alone, and a command refuses the file once others can read it. Without the flag, the sign-in fails there and revokes what it received.
• The page that opens shows costfluent login as an app Costfluent has not verified and that returns only to your computer, since its answer comes back to the command on this computer: allow it when you ran the command yourself.
• --no-browser prints the address to open instead of opening your browser. --timeout sets how long the command waits for you to approve, such as --timeout 10m; it waits 5 minutes otherwise.
• COSTFLUENT_BASE_URL chooses the API as for every command, and each API keeps its own sign-in.
• When the sign-in has ended or was revoked, a command exits with 3 and asks you to run costfluent login again.

Commands

A flag is the tool's argument with hyphens: the start_date of query_costs is --start-date. A flag that takes a list, such as --group-by, is given once for each value.

costfluent list-commitments and costfluent get-commitment-coverage read the commitments a workspace's connections hold and how much of the eligible usage they covered.

Connect an assistant

costfluent mcp install prints the entry that starts costfluent-mcp in your assistant, or adds it to the assistant's configuration file with --write.

Post cost estimates from CI

costfluent estimate submit posts the estimate Infracost makes for a Terraform pull request to Costfluent, and costfluent estimate apply records that the change was applied, with the ids Terraform gave the resources it created or replaced. With those ids Costfluent finds each resource in your billing data and compares the estimate with the cost that followed. The two commands do from any CI what Costfluent's cost estimate GitHub Action does in GitHub Actions, converting Infracost's and Terraform's JSON with the Action's own programs, so both post the same estimate.

GitLab CI

This job runs on merge requests, after a plan job that keeps infracost.json and plan.json as artifacts. COSTFLUENT_API_TOKEN is a masked CI/CD variable.

Code
cost-estimate:
  image: golang:1.27.4
  needs: [plan]
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  script:
    - go install github.com/costfluent/costfluent-mcp/cmd/costfluent@latest
    - >-
      costfluent estimate submit
      --workspace-id wsp_8f3k2m
      --repository "$CI_PROJECT_PATH"
      --pull-request "$CI_MERGE_REQUEST_IID"
      --infracost-json infracost.json
      --terraform-plan-json plan.json
      --commit "$CI_COMMIT_SHA"
      --url "$CI_MERGE_REQUEST_PROJECT_URL/-/merge_requests/$CI_MERGE_REQUEST_IID"
      --fail-above 500

Azure Pipelines

This pipeline runs on pull requests in Azure Repos, which a build validation policy on the target branch starts. COSTFLUENT_API_TOKEN is a secret pipeline variable, which a step sees only when its env maps it.

Code
trigger: none

pool:
  vmImage: ubuntu-24.04

steps:
  - task: GoTool@0
    inputs:
      version: 1.27.4
  - script: |
      go install github.com/costfluent/costfluent-mcp/cmd/costfluent@latest
      echo "##vso[task.prependpath]$HOME/go/bin"
    displayName: Install costfluent
  # Run Terraform and Infracost here, writing plan.json and infracost.json.
  - script: >-
      costfluent estimate submit
      --workspace-id wsp_8f3k2m
      --repository "$(Build.Repository.Name)"
      --pull-request "$(System.PullRequest.PullRequestId)"
      --infracost-json infracost.json
      --terraform-plan-json plan.json
      --commit "$(System.PullRequest.SourceCommitId)"
      --fail-above 500
    displayName: Post the cost estimate
    env:
      COSTFLUENT_API_TOKEN: $(COSTFLUENT_API_TOKEN)

Record the apply

After the merged change is applied from its saved plan, in any CI:

Code
terraform show -json tfplan > plan.json
terraform apply -input=false tfplan
terraform show -json > state.json
costfluent estimate apply --workspace-id wsp_8f3k2m --repository acme/infra --pull-request 42 \
  --terraform-plan-json plan.json --terraform-state-json state.json

• submit creates the pull request's estimate on its first post and replaces it on each later one until the change is applied. A diff that changes no priced resource posts nothing, and the command exits 0.
• Both commands print the estimate's receipt: its id and state and, from submit, the planned monthly cost before and after, the change and how many resources Infracost could not price, as Costfluent computed them in the estimate's currency. A line on stderr says whether the estimate was created or updated.
• --fail-above is judged after the receipt is printed and compares the exact amounts: a change equal to --fail-above passes, a change above it exits 4, and a negative change never does. When Costfluent answers without the planned totals, a warning says --fail-above is not applied and the command exits 0, rather than failing every pull request on a change it cannot read.
• apply warns of each resource the plan created or replaced that the state holds no id for, and leaves it out. A pull request with no estimate in the workspace has nothing to apply: the command says so with the API's reason and exits 0.
• A wrong or missing flag, or an input file that is not JSON, exits 2 before any request.

How it behaves

• A command prints JSON when its output goes to a file, a pipe or a CI log, and a table when it goes to a terminal; --output json or --output table chooses. Amounts keep every digit the API sends.
• A command exits 0 when it succeeded, 1 when the call failed, 2 when the command line is wrong, 3 when the token is missing or refused or lacks the capability the command needs, before the command reads anything, and 4 when a threshold you set was exceeded, as costfluent estimate submit --fail-above sets one.
• An error goes to stderr: the API's error as JSON, with its status, code, detail and trace id, when stderr is not a terminal, and one line when it is.
• A list returns one page, as the tool does; the result names the next page, which --page reads.
• Every command counts against the token's request limit, and waits out a short limit as the MCP server does.
• A table writes control characters in names, titles and tag values as escapes, because your users and your cloud accounts write them and a terminal would act on them.
• No command prints the token, and costfluent mcp install writes it into a file only with --embed-token, which needs --write.
• --write keeps every other server in the file and refuses a file that already has a costfluent entry unless --force replaces it. It leaves a file it cannot read as plain JSON, such as one with comments, unchanged.

Related

• MCP server
• API authentication
• API reference