MCP Server Reference

Use the CloudZero MCP server to query cost data, retrieve optimization recommendations, explore Dimensions, access and send telemetry, manage organization context, evaluate business metrics, and log and manage Insights. These are the same tools that power AI Hub. In the Model Context Protocol (MCP), tools are functions that an MCP server exposes for AI clients to call.

This reference documents each tool, its parameters, and which skills use it. Skills are guided analysis workflows available through the CloudZero Plugin that combine multiple tools into structured investigations. For setup instructions, see Set Up AI Hub.

Authentication

The MCP server supports three authentication methods:

• CloudZero account (OAuth): On first use, a browser window opens to sign in. Sessions persist across AI tool restarts. See Set Up AI Hub for setup.
• API key: Pass an X-Api-Key header for automation, CI/CD, or clients that do not support OAuth. API key usage is metered with a daily quota. See API Key Authentication for setup.
• OAuth client: Register a client ID and client secret for an enterprise agent platform that cannot register itself with the MCP server. Users still sign in individually, so data access controls and permission sets apply. See Connect an Agent Platform with MCP OAuth Clients for setup.

Access and permissions

The MCP server enforces the same roles and permissions as the CloudZero application.

Data access controls

Your role's data access filters apply to all cost queries. If your role restricts visibility to specific Dimensions (for example, only Team = Engineering), the MCP server returns only matching data. API key users have full access to all cost data in the organization.

The Insights tools (create_insight, update_insight, and delete_insight) and the Monitors and Incidents write tools (create_monitor, update_monitor, update_incident, and create_incident_ticket) require full data access. If your role has any data access filters, these tools return an error stating that they require full data access.

See Users and Permissions for details.

Permission sets

Some tools require specific permission sets on your role. If the required permission set is not granted, the tool returns an authorization error.

The MCP Settings permission sets control who can manage OAuth clients. They grant no access to the tools below.

All other tools are available to any authenticated user.

Usage quotas

API key calls are subject to a daily usage quota per organization. OAuth users are not metered.

Quota warnings

As your organization approaches the daily limit, the MCP server appends a warning to tool results at the following thresholds:

Quota exceeded

When the daily quota is exceeded, the MCP server returns an error and no further API key tool calls succeed until the quota resets at midnight UTC.

Response size limit

The MCP server enforces a 5 MB maximum on individual tool responses. When a query produces a response above the limit, the server returns a tool error with the actual response size and guidance for narrowing the query:

"Tool '<tool_name>' produced a response of <X.X> MB, which exceeds the 5 MB limit. To recover, narrow your query: shrink date_range, add or tighten filters, reduce the limit parameter, or change group_by to a less granular dimension."

AI agents that receive this error can retry with a narrower query automatically.

Per-tool limit caps

Query-style tools also enforce a maximum value for the limit parameter. Requests that exceed the cap are rejected before the tool runs.

Tools

Allocations

get_available_dimensions

Lists all available Dimensions for filtering or grouping cost data, including both standard CloudZero Dimensions and custom Dimensions.

Parameters

Skills: custom-dimension-analysis, tag-coverage-analysis, understand-cloudzero-organization

get_dimension_values

Retrieves the available values for a specific Dimension, such as all account names, service types, or team values.

Parameters

Skills: cost-comparison, custom-dimension-analysis, tag-coverage-analysis, understand-cloudzero-organization

Business Metrics

A business metric is a saved formula over your billing data and telemetry streams, such as cost per booking or cost per active user. These tools list the metrics your organization has saved, read one in full, evaluate one over a date range, save a new one, and delete one. A saved metric carries its author's filters, scaling, and rollup, so evaluating it returns the same numbers as the web app.

save_business_metric and delete_business_metric require the Business Metrics permission set. The other four tools are available to any authenticated user.

The filters and group_by parameters of evaluate_business_metric take bare Dimension IDs such as CZ:Service, the same syntax as the filters of get_cost_data. A formula writes the same Dimension in brackets, as [CZ:Service]. Use get_available_dimensions to find Dimension IDs and get_dimension_values to find valid values.

business_metric_history

Lists a business metric's saved versions, newest first, including deletions. Each version is the metric as it was saved at that time.

Parameters

Response

versions holds the saved versions, each with the metric fields. A version that recorded a deletion has deleted set to true and no formula. A version whose formula your role cannot read keeps its place and its name, and has restricted set to true.

Pass next_before back as before to read older versions. An empty page means there are no older versions.

Skills: Available for direct business metric management

delete_business_metric

Deletes a saved business metric. It no longer appears in lists or in the web app, and its earlier versions stay in its history. Metrics whose formulas reference it stop evaluating until the reference is removed. Deleting a metric that is already deleted returns the existing deletion. save_business_metric cannot restore a deleted metric.

Parameters

Response

Returns the metric's metric_id, the version that recorded the deletion, and the metric's name.

Skills: Available for direct business metric management

evaluate_business_metric

Evaluates a business metric over a date range and returns one value per bucket. Pass metric_id for a saved metric, or formula with grain to try formula text before saving it, never both. grain, unit, decimal_places, and source_filters apply only to formula; a saved metric carries its own.

granularity may be coarser than the metric's grain, which rolls the metric up, and never finer. A Dimension the metric cannot reach is refused, and the error names it; get_business_metric lists the Dimensions a saved metric accepts. To check formula text without running a query, use save_business_metric with dry_run.

Parameters

Response

timestamps holds one date per bucket. Each entry in series has a group, which maps each group_by Dimension ID to that series' value, and values, which holds one decimal string or null for every timestamp, in the order of timestamps. A null value is a bucket with no value. With no group_by, the response holds one series with an empty group.

grain is the bucket size the metric was served at. unit and decimal_places come from the metric's definition. truncated is true when groups past max_groups were dropped. For an unsaved formula, sources lists the billing data and telemetry streams the formula reads; it is null for a saved metric.

A response holds at most 5,000 values, counting buckets times groups. When a long range at a fine granularity would exceed that, fewer groups come back and note says how many were kept. When the buckets alone exceed 5,000, the tool returns an error. In both cases, use a coarser granularity or a shorter range.

Example

Evaluate the saved cost per booking metric that get_business_metric returns below for the first three days of September, and break it down by region, keeping the two largest regions:

{
  "metric_id": "7c1e4a2b-3d5f-4e6a-9b8c-0d1e2f3a4b5c",
  "start_date": "2026-09-01",
  "end_date": "2026-09-03",
  "granularity": "daily",
  "group_by": ["CZ:Region"],
  "max_groups": 2
}

{
  "timestamps": ["2026-09-01", "2026-09-02", "2026-09-03"],
  "series": [
    {
      "group": { "CZ:Region": "us-east-1" },
      "values": ["0.42", "0.39", "0.41"]
    },
    {
      "group": { "CZ:Region": "eu-west-1" },
      "values": ["0.55", "0.58", null]
    }
  ],
  "grain": "daily",
  "unit": "USD",
  "decimal_places": 2,
  "truncated": true,
  "sources": null,
  "note": null
}

Cost per booking in us-east-1 held near $0.41 across the three days, and eu-west-1 ran higher. The last eu-west-1 bucket has no value. truncated is true because the metric covers more regions than the two returned, so raise max_groups to see the rest.

Skills: Available for direct business metric analysis

get_business_metric

Gets a saved business metric's current version, with the Dimensions it can be grouped and filtered by. To edit the metric, pass these fields back to save_business_metric with version as expected_version.

Parameters

Response

Returns the current version with the metric fields, plus dimensions and note.

dimensions lists the Dimension IDs that evaluate_business_metric accepts in group_by and filters for this metric. It is null when the metric reads only billing data, where any Dimension that get_available_dimensions returns with include_hidden set applies, or when the metric cannot be evaluated. note then says which case applies.

Example

Read the saved cost per booking metric that the evaluate_business_metric example uses:

{
  "metric_id": "7c1e4a2b-3d5f-4e6a-9b8c-0d1e2f3a4b5c"
}

{
  "metric_id": "7c1e4a2b-3d5f-4e6a-9b8c-0d1e2f3a4b5c",
  "version": "2026-08-28T16:04:11.238Z",
  "name": "Cost per booking",
  "description": "Real cost per completed booking",
  "formula": "[Cost:Real Cost] / Sum([Telemetry:bookings])",
  "grain": "daily",
  "unit": "USD",
  "decimal_places": 2,
  "source_filters": [
    {
      "source": { "kind": "billing_data" },
      "condition": "[CZ:Service] = \"AmazonS3\""
    }
  ],
  "sources": [
    { "kind": "billing_data" },
    { "kind": "telemetry", "telemetry_stream": "bookings" }
  ],
  "updated_by": "[email protected]",
  "updated_via": "web",
  "deleted": false,
  "restricted": false,
  "dry_run": false,
  "dimensions": [{ "fqdid": "CZ:Region", "name": "Region" }],
  "note": null
}

The formula divides real cost by the sum of the bookings telemetry stream, and the source filter limits the cost side to Amazon S3. dimensions names the one Dimension ID this metric accepts, so evaluate_business_metric takes CZ:Region in group_by and filters and refuses any other Dimension. Pass version back as expected_version to save a change.

Skills: Available for direct business metric management

list_business_metrics

Lists the saved business metrics visible to you, ordered by metric ID, each with its formula as text.

Parameters

Response

metrics holds one entry per metric with the metric fields, and total_count is the number of metrics visible to you. A page can hold fewer than limit metrics. Pass next_offset back as offset to get the next page; it is null after the last page.

Metric fields

business_metric_history, get_business_metric, list_business_metrics, and save_business_metric return a metric as these fields.

Skills: Available for direct business metric management

save_business_metric

Creates a business metric, or replaces a saved metric's definition, from formula text. Every definition field is required and replaces the saved value, so a null or empty field clears it. To change one field, send the others back as get_business_metric returned them, source_filters included.

To replace a metric, pass its metric_id and the version you read as expected_version. If the metric was changed or deleted since you read it, nothing is saved and the error names the current version. This tool cannot restore a deleted metric.

With dry_run, the definition is validated as a save would validate it and nothing is stored. The errors are the same, expected_version is not checked, and the response has no version. Use it to check formula and filter syntax, and evaluate_business_metric to see a formula's values.

Parameters

Formula syntax

Brackets name an input: [Cost:Real Cost], [Telemetry:<stream>], [Metric:<name>], or a Dimension as [CZ:Service] or [Dimension:<display name>]. A bare [name] works when only one input has that name. Combine terms with +, -, *, / and parentheses.

A telemetry stream needs an aggregation: Sum, Average, Min, Max, Median, or Latest, as in Sum([Telemetry:bookings]). A Dimension needs CountDistinct. A cost type is already its bucket's sum, so Sum([Cost:Real Cost]) is saved as [Cost:Real Cost].

Filter(term, condition) limits one term, as in Filter([Cost:Real Cost], [CZ:Service] = "AmazonS3"). A condition is [d] = "x", [d] != "x", In([d], ("x", "y")), or Contains([d], "x"), joined with lowercase and, or, and not.

Each entry in source_filters pairs a source with a condition written in the same condition syntax, and limits every part of the formula that reads that source to the rows the condition matches. A source is either {"kind": "billing_data"} or {"kind": "telemetry", "telemetry_stream": "<name>"}:

[
  {
    "source": { "kind": "billing_data" },
    "condition": "[CZ:Service] = \"AmazonS3\""
  }
]

Response

Returns the saved version with the metric fields. With dry_run, version is null and dry_run is true.

Skills: Available for direct business metric management

Context

Organization context is the guidance every agent reads at the start of a cost analysis session. It has two sections with different owners:

Each tool writes only its own section and carries the other forward unchanged. Custom Instructions take precedence when the two overlap.

Keep custom guidance across /init

The /init prompt (/plugin:cost-analyst:cloudzero:init in the Claude Code Plugin) replaces Generated Context in full on every run and never edits Custom Instructions. To add a rule that persists, such as "exclude tax and support charges by default," save it to Custom Instructions with set_org_context or ask the agent to save it for you. For setup steps, see Set Up AI Hub.

If you ran /init before context was split into two sections, your earlier generated content is stored as Custom Instructions and preserved as written. The next /init run offers to move those sections out of Custom Instructions and removes only what you confirm.

get_org_context

Retrieves your organization's context for cost analysis. The instructions field returns up to two sections: # Custom Instructions, authored by your organization with set_org_context, followed by # Generated Context, derived from query history by the /init prompt. Custom Instructions take precedence. A section is omitted when it is empty.

Parameters

Skills: understand-cloudzero-organization, all other skills (consume cached context)

get_org_context_versions

Lists all available versions of organization context for reviewing historical configurations. Every save with set_org_context or set_generated_context creates a timestamped version. Prior versions are retained for 30 days; the current version never expires.

Parameters

None.

Skills: understand-cloudzero-organization

set_generated_context

Replaces the Generated Context section with content derived from recent query history. The /init prompt calls this tool after you review and confirm the proposed context. Custom Instructions are preserved exactly as stored, so every rule a person added survives the refresh.

Parameters

Skills: Used by the /init prompt rather than by a skill

set_org_context

Replaces the Custom Instructions section with guidance you want every agent to follow: business rules, Dimension preferences, team structures and cost ownership, cost allocation policies. The tool leaves Generated Context unchanged, and /init in turn never modifies Custom Instructions. Because the call replaces the whole section, pass the full updated text when adding to existing instructions, not just the addition.

Parameters

Skills: understand-cloudzero-organization

CostFormation

These tools read the YAML Dimension definitions you manage with CostFormation.

download_costformation

Returns a pre-signed, temporary download link for a CostFormation Dimension definition file, along with metadata about when the definition was last updated and by whom. The link expires shortly after it is issued. Request a new link rather than retrying an expired one.

Parameters

Skills: Available for direct CostFormation review and export workflows

get_costformation_vers

Lists the available versions of a CostFormation Dimension definition. Returns version identifiers with human-readable creation dates, most recent first. Use this to find a version before downloading it with download_costformation.

Parameters

Skills: Available for direct CostFormation review and export workflows

Incidents

These tools let an agent review the anomaly incidents that monitors raise, update their status, and create tickets for them. update_incident and create_incident_ticket require full data access.

create_incident_ticket

Creates a Jira or ServiceNow ticket for an incident and links it to the incident. Use list_ticket_projects to choose project_key and ticket_type; you can omit both only when your organization has a single project and ticket type. Calling this tool again for an incident that already has a ticket creates no second ticket and returns the existing ticket instead. If the project's ticket type has required fields, the error names them; call get_ticket_fields and pass them in fields. If the error says a field is invalid, use the id from allowed_values. Requires full data access.

Parameters

Skills: Available for direct incident management

get_incident

Retrieves one anomaly incident in full: description, cost impact, anomalous days, affected resources, and filters. affected_resources is capped; affected_resource_count is the full number.

Parameters

Skills: Available for direct incident management

get_ticket_fields

Lists the fields that a project's ticket type accepts when you create a ticket, with each field's id, name, type, and whether it is required. For ServiceNow, required is advisory. For Jira, the list is the first 50 fields on the ticket type's create screen. Pass the values you choose to create_incident_ticket in fields, keyed by field id. Jira ignores field ids that are not on the ticket type's create screen; ServiceNow writes any column you name on the table, so only use ids returned by get_ticket_fields.

Parameters

Field values

The Labels field takes one label with no spaces. The Jira Team field takes the Atlassian team id (a UUID), which this tool cannot list.

Skills: Available for direct incident management

list_incidents

Lists anomaly incidents one page at a time, with each incident's monitor, title, cost impact, trend, status, spend status, and start date. Pass pagination.next_cursor back as cursor to get the next page, and keep the other filters and sort unchanged between pages. pagination.total_count is the count for the whole result, not the page. Use get_incident for one incident's detail.

Parameters

Skills: Available for direct incident management

list_ticket_projects

Lists the Jira and ServiceNow projects and ticket types that incident tickets can be created in. Use a project's project_key and one of its ticket_types as the arguments of create_incident_ticket. skipped_integrations names connected integrations that could not be reached, so the list can be partial. Returns an error if no ticket integration is connected.

Parameters

None.

Skills: Available for direct incident management

update_incident

Changes an incident's status, adds a comment, or both. Pass at least one of status or comment. The status change is applied first, then the comment, and both appear on the incident's activity timeline. Requires full data access.

Resolving an incident requires resolution_reason. resolution_reason and resolution_reason_detail are valid only when status is resolved.

Parameters

Resolution reasons

Skills: Available for direct incident management

Insights

These tools let an agent log a finding as an Insight and track it as your team works on it. They act on the same Insights you create from Explorer, and the results appear on the Insights tab in Optimize. All three tools require full data access.

update_insight and delete_insight work only on Insights that a person created, through Explorer or with create_insight. They reject Insights that CloudZero generates automatically, such as cost anomalies and recommendations.

create_insight

Creates an Insight with the same fields and validation as the Create Insight form in Explorer. CloudZero removes HTML from the title and description, and accepts a link only when it is an https:// URL on a cloudzero.com domain, such as a link back to an Explorer query. Returns the new Insight, including its ID.

Parameters

Skills: Available for direct Insight logging

delete_insight

Permanently deletes an Insight and all of its comments. A deleted Insight cannot be restored. To close an Insight and keep its history, set its status to addressed or ignored with update_insight instead. Returns the deleted Insight's ID and the number of comments deleted.

Parameters

Skills: Available for direct Insight management

update_insight

Changes the status or effort of a manually created Insight. Pass at least one of status or effort; fields you leave out keep their current values. Returns the updated Insight.

Parameters

Insight status values

Skills: Available for direct Insight management

Kubernetes

get_container_usage

Reports how much CPU and memory Kubernetes workloads actually use versus what they request, for rightsizing and container-efficiency analysis. Data comes from the CloudZero Agent for Kubernetes, so it covers only clusters running the agent. Cost is not included here; use the cost tools for spend and pair the two to size the savings available from rightsizing.

Parameters

Partition values

Valid filters dimensions are k8s_cluster, k8s_namespace, k8s_workload, cloud_account_id, cloud_provider, and cloud_region.

Response

Each entity reports p95_used (the 95th-percentile amount used over the date range, which absorbs short spikes), requested (the amount reserved), and efficiency (p95_used / requested). Efficiency well under 1.0 means the workload reserves far more than it uses and is a rightsizing candidate; near 1.0 means it is sized about right; above 1.0 means it is using more than it requested and risks CPU throttling or OOM kills. Efficiency is capped at 2.0, so that value means "at least twice its request" rather than an exact ratio. Any of the three values can be null, most often for workloads that set no resource requests.

CPU is reported in cores and memory in GiB. The response echoes cpu_unit, memory_unit, and the effective date_range used.

The response holds at most limit entities, chosen by the most CPU requested, so the largest reservations come first. total_entities reports how many entities matched the query, and truncated is true when that count is higher than the number returned. Organization-wide k8s_workload queries can match tens of thousands of workloads. To see past the largest ones, narrow the query with a k8s_cluster or k8s_namespace filter rather than raising limit.

Skills: Available for direct Kubernetes rightsizing lookups

Monitors

Monitors watch the spend that matches a set of filters and raise incidents when they detect an anomaly. These tools list, read, create, and change monitors. They are in preview and work only for organizations where Monitors is enabled; otherwise they return "Monitors aren't enabled for this organization." create_monitor and update_monitor require full data access.

Monitor filters and grouping use Dimension IDs such as CZ:Service, the same syntax as the filters of get_cost_data. Use get_available_dimensions to find Dimension IDs and get_dimension_values to find valid values.

create_monitor

Creates a monitor that watches the spend matching filter_set and raises incidents on anomalies. An empty filter_set watches all spend. CloudZero checks that the filters match cost data, so a monitor with no matching spend can be rejected. If another monitor already has the same filter_set, group_by, threshold, and cost_type, the tool creates nothing and returns an error and the existing monitor's ID. The creation appears on the monitor's activity timeline. Returns the new monitor, including its ID. Requires full data access.

Parameters

Monitor cost types

Threshold

Skills: Available for direct monitor management

get_monitor

Retrieves one monitor in full: description, filter_set, group_by, cost type, and threshold. filter_set and group_by use Dimension IDs.

Parameters

Skills: Available for direct monitor management

list_monitors

Lists every monitor in your organization in one response, with no paging. Each monitor includes its name, enabled state, cost type, group_by Dimensions, and open incident count. Use get_monitor for a monitor's filters, threshold, and description.

Parameters

None.

Skills: Available for direct monitor management

update_monitor

Changes a monitor. Fields you leave out keep their current values; pass at least one change. filter_set and group_by replace the stored values. A change that would give the monitor the same filter_set, group_by, threshold, and cost_type as another monitor returns an error and the existing monitor's ID. The change appears on the monitor's activity timeline. Returns the updated monitor. Requires full data access.

System monitors accept only threshold and is_enabled changes.

Parameters

Skills: Available for direct monitor management

Optimization

get_optimize_recs

Retrieves cost optimization recommendations from CloudZero, including rightsizing, Reserved Instance, and Savings Plan opportunities.

Parameters

Status values

Skills: service-cost-deep-dive

get_realized_savings

Retrieves realized savings from addressed Optimize recommendations over a time period, with optional breakdowns by Dimension.

Parameters

Skills: Available for direct savings analysis and reporting

Query

get_cost_data

Queries cost data from CloudZero with support for grouping, filtering, and time-based analysis. This is the primary tool for retrieving cost information.

Parameters

Response

Each result row includes projected_row_count, the number of underlying cost records aggregated into that row. This is useful for diagnosing Dimension cardinality and allocation complexity. The value is null for hourly granularity.

Skills: cost-anomaly-detection, cost-comparison, cost-spike-investigation, cost-trend-analysis, custom-dimension-analysis, service-cost-deep-dive, tag-coverage-analysis, top-cost-drivers

get_recent_query_history

Returns an analysis of your organization's cost query patterns over the last 30 days, including the most frequently used queries (overall and over the last 7 days), the most frequently used Dimensions, and total query counts.

Parameters

None.

Skills: All skills (for context)

Reference

get_reference_info

Retrieves reference documentation about CloudZero concepts, workflows, and best practices.

Parameters

Reference types

Skills: understand-cloudzero-organization, all skills (for reference lookups)

Resource

get_resource_metadata

Retrieves metadata for a single cloud resource by its CloudZero Resource Name (CZRN), including provider service, resource type, lifecycle state, tags, and relationships.

Parameters

Skills: Available for direct resource metadata lookups

Telemetry

create_telemetry_stream

Creates a telemetry stream and writes its first data points in the same call. Add later data points with send_telemetry_data.

If a stream with that name already exists, the tool returns an error. If two creates of the same new name overlap, both succeed only when they send data of the same shape, and then the losing call's data merges into the stream the other created. If stream type, target Dimensions, or granularity differ, the losing call returns an error.

Metric streams created by this tool are daily, and passing any other granularity for a metric stream returns an error. Create a monthly metric stream in Settings > Telemetry Streams. Every data point in the batch must use the same set of target Dimensions. For an allocation stream, granularity sets the stream's time bucket. Granularity is one value per call, not a per-record field.

The result returns the stream name and count, the number of data points accepted. If CloudZero accepts fewer data points than were sent, the tool returns an error. Ingestion into the store that get_telemetry_data reads runs hourly. A query immediately after a successful create returns no rows until that ingestion runs.

For stream status and where the data appears, see Send unit cost and allocation data.

Parameters

Data point fields

Skills: Available for direct telemetry stream creation

get_telemetry_data

Retrieves telemetry metrics from configured telemetry streams for correlating costs with operational metrics.

Parameters

Skills: cost-trend-analysis, service-cost-deep-dive

get_telemetry_streams

Lists all available telemetry streams configured in your CloudZero organization.

Parameters

None.

Skills: cost-trend-analysis, service-cost-deep-dive

send_telemetry_data

Sends allocation or metric data points to a telemetry stream that already exists. The tool reads the stream type from that stream. Create the stream first with create_telemetry_stream.

A data point with a value of zero is rejected under replace and replace_period, and accepted under sum.

The result returns count, the number of data points accepted. If CloudZero accepts fewer data points than were sent, the tool returns an error. Ingestion into the store that get_telemetry_data reads runs hourly. A query immediately after a successful send returns no rows until that ingestion runs.

Parameters

Operation values

Skills: Available for direct telemetry uploads

Parameter reference

Cost types

The cost_type parameter accepts the following values:

Granularity options

The granularity parameter accepts:

Omit the granularity parameter to return the total for the period with no time breakdown.