The CloudZero MCP server exposes tools that skills use to query your cost data. While skills handle the analysis workflow, MCP tools provide the underlying data access. This reference documents all available tools, their parameters, and which skills use them.

Authentication and authorization

Authentication

The MCP server supports two authentication methods:

CloudZero account (OAuth)

On first use, the MCP server opens a browser window to sign in to CloudZero
If you already have an active CloudZero session, authentication is automatic
Sessions persist across restarts — you do not need to sign in again until the session expires

API key

Pass an X-Api-Key header instead of signing in through the browser
API keys are organization-level tokens that grant full access to all cost data for the associated organization
Useful for automation, CI/CD pipelines, and MCP clients that do not support browser-based OAuth
API key usage is metered with a daily quota (see Usage quotas)

For setup instructions, see API key authentication.

Authorization

The MCP server enforces the same roles and permissions as the CloudZero application. Your access is governed by two mechanisms:

Data access controls

Your role's data access filters apply to all cost queries made through the MCP server. If your role restricts visibility to specific dimensions (for example, only Team = Engineering), the MCP server returns only data matching those filters. This works identically to the CloudZero web application.

API key users have full access to all cost data in the associated organization. Data access filters do not apply.

See Role-based Access Control for details on configuring data access.

Permission sets

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

Tool	Required permission set
`get_telemetry_data`	Telemetry Stream Settings (View Telemetry Streams)
`get_telemetry_streams`	Telemetry Stream Settings (View Telemetry Streams)
`get_optimize_recs`	Optimize (View Recommendations)
`set_org_context`	Organization Administration (Modify Organization Settings)

All other tools are available to any authenticated user.

ℹ️
API key users are not subject to permission set restrictions. All tools are available to any valid API key with the ai-hub:mcp scope.

See View and Manage Roles for details on configuring permission sets.

Usage quotas

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

Daily limit

Each organization has a daily quota of tool calls made via API keys. The default quota is 3,000 tool calls per UTC calendar day. The quota resets at midnight UTC.

Usage warnings

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

Threshold	Example warning
50%	"Your organization has used 50% (1500/3000) of the daily API call quota."
75%	"Your organization has used 75% (2250/3000) of the daily API call quota."
90%	"Your organization has used 90% (2700/3000) of the daily API call quota."

These warnings appear as additional text appended to the tool result. Your MCP client displays them alongside the tool output.

Quota exceeded

When the daily quota is exceeded, the MCP server returns an HTTP 429 status code with a Retry-After header indicating how many seconds remain until the quota resets at midnight UTC. No further API key tool calls succeed until the quota resets.

The error message reads: "Daily API key organization quota exceeded (3000/3000). Quota resets at midnight UTC."

Tools Overview

Tool	Capability	Description
get_cost_data	Query	Query cost data with filters and groupings
get_recent_query_history	Query	View recent cost queries
get_available_dimensions	Allocations	List dimensions for filtering/grouping
get_dimension_values	Allocations	Get values for a specific dimension
get_org_context	Context	Retrieve organization-specific context
set_org_context	Context	Set organization context for queries
get_org_context_versions	Context	List available context versions
get_reference_info	Reference	Get reference documentation
get_user_organizations	Reference	List accessible organizations
get_optimize_recs	Optimization	Get cost optimization recommendations
get_telemetry_data	Telemetry	Retrieve telemetry metrics
get_telemetry_streams	Telemetry	List available telemetry streams

get_cost_data

Purpose

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

Parameters

Parameter	Required	Description
`group_by`	No	Dimensions to group results by
`filters`	No	Filter criteria to narrow results
`date_range`	No	Time period to query
`granularity`	No	Time granularity: `hourly`, `daily`, `weekly`, `monthly`
`cost_type`	No	Type of cost metric (default: `real_cost`)
`limit`	No	Maximum results to return

Used by

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

get_recent_query_history

Purpose

Retrieves the history of recent cost queries made during the session, useful for reviewing past analysis or debugging.

Parameters

Parameter	Required	Description
`limit`	No	Maximum number of queries to return

Used by

All skills (for context and debugging)

get_available_dimensions

Purpose

Lists all available dimensions that can be used for filtering or grouping cost data, including both standard CloudZero dimensions and custom User:Defined dimensions.

Parameters

Parameter	Required	Description
`filter`	No	Filter dimensions by name pattern
`limit`	No	Maximum dimensions to return
`force_refresh`	No	Bypass cache and fetch fresh data
`include_hidden`	No	Include hidden dimensions in results

Used by

understand-cloudzero-organization
custom-dimension-analysis
tag-coverage-analysis

get_dimension_values

Purpose

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

Parameters

Parameter	Required	Description
`dimension`	Yes	The dimension to get values for
`date_range`	No	Time period to scope the values
`match`	No	Filter values by pattern
`limit`	No	Maximum values to return

Used by

understand-cloudzero-organization
custom-dimension-analysis
tag-coverage-analysis
cost-comparison

get_org_context

Purpose

Retrieves organization-specific context including custom dimensions, workflows, naming conventions, and cost allocation policies.

Parameters

Parameter	Required	Description
`version`	No	Specific context version to retrieve

Used by

understand-cloudzero-organization
All other skills (consume cached context)

set_org_context

Purpose

Sets the organization context that will be used for subsequent queries. This configures how cost data is interpreted and analyzed.

Parameters

Parameter	Required	Description
`context`	Yes	The context configuration to set

Used by

understand-cloudzero-organization

get_org_context_versions

Purpose

Lists all available versions of organization context, allowing you to review historical context configurations or switch between versions.

Parameters

None.

Used by

understand-cloudzero-organization

get_reference_info

Purpose

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

Parameters

Parameter	Required	Description
`reference_type`	Yes	Type of reference to retrieve

Reference types

cost_types - Documentation on available cost metrics
dimensions - Documentation on standard dimensions
cost_analysis_workflow - Best practices for cost analysis
custom_dimensions_workflow - Working with custom dimensions
filtering_workflow - How to filter cost data effectively
cost_analyst_instructions - General Cost Analyst guidance

Used by

understand-cloudzero-organization
All skills (for reference lookups)

get_user_organizations

Purpose

Lists all organizations the current user has access to, useful for multi-organization environments.

Parameters

None.

Used by

understand-cloudzero-organization

get_optimize_recs

Purpose

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

Parameters

Parameter	Required	Description
`status`	No	Filter by recommendation status
`limit`	No	Maximum recommendations to return
`offset`	No	Pagination offset
`sort_key`	No	Field to sort results by
`sort_order`	No	Sort direction: `asc` or `desc`

Status values

not_started - Recommendations not yet acted upon
in_progress - Recommendations being implemented
addressed - Completed recommendations
ignored - Dismissed recommendations

Used by

service-cost-deep-dive (for optimization opportunities)

get_telemetry_data

Purpose

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

Parameters

Parameter	Required	Description
`stream`	No	Specific telemetry stream to query
`date_range`	No	Time period for telemetry data
`granularity`	No	Time granularity: `hourly`, `daily`, `weekly`, `monthly`

Used by

service-cost-deep-dive (for usage correlation)
cost-trend-analysis (for metric correlation)

get_telemetry_streams

Purpose

Lists all available telemetry streams configured in your CloudZero organization.

Parameters

None.

Used by

service-cost-deep-dive
cost-trend-analysis

Parameter Reference

Cost types

The cost_type parameter accepts the following values:

Value	Description
`real_cost`	Actual cost after all discounts (default)
`billed_cost`	Cost as it appears on your bill
`on_demand_cost`	Cost at on-demand pricing
`amortized_cost`	Cost with upfront payments spread over term
`discounted_cost`	Cost showing discount amounts
`discounted_amortized_cost`	Amortized cost with discounts applied

Granularity options

The granularity parameter accepts:

hourly - Hour-by-hour breakdown
daily - Day-by-day breakdown
weekly - Week-by-week breakdown
monthly - Month-by-month breakdown
None - Total for the period (no time breakdown)