MCP Server Reference
Use the CloudZero MCP server to query cost data, retrieve optimization recommendations, explore Dimensions, access telemetry, and manage organization context. 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 two 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-Keyheader 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.
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.
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.
| Tool | Required permission set | Required scope |
|---|---|---|
download_costformation | Dimension Definition Settings (View Dimension Definitions) | cost-contexts:get-definition-download-link |
get_costformation_vers | Dimension Definition Settings (View Dimension Definitions) | cost-contexts:get-contexts |
get_optimize_recs | Optimize (View Recommendations) | insights-workflow:list-recommendations |
get_realized_savings | Optimize (View Recommendations) | insights-workflow:get-realized-savings |
get_resource_metadata | Resource Provider (View resource provider) | resource-provider:get-resource-by-czrn |
get_telemetry_data | Telemetry Stream Settings (View Telemetry Streams) | unit-cost:get-records |
get_telemetry_streams | Telemetry Stream Settings (View Telemetry Streams) | unit-cost:streams |
set_org_context | Organization Administration (Modify Organization Settings) | czca-server:set-org-context |
All other tools are available to any authenticated user.
API key users have full access to all cost data and all tools. Role-based data access filters and permission set restrictions do not apply. Use OAuth authentication when Role-based access control is required.
Usage quotas
API key calls are subject to a daily usage quota per organization. OAuth users are not metered.
Each organization has a default quota of 3,000 API key tool calls per UTC calendar day. The quota resets at midnight UTC.
Quota 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." |
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.
| Tool | Maximum limit |
|---|---|
get_available_dimensions | 1,000 |
get_cost_data | 5,000 |
get_dimension_values | 1,000 |
get_optimize_recs | 1,000 |
get_telemetry_data | 5,000 |
Tools
| Category | Tool | Description |
|---|---|---|
| Allocations | get_available_dimensions | List Dimensions for filtering and grouping |
| Allocations | get_dimension_values | Get values for a specific Dimension |
| Context | get_org_context | Retrieve organization-specific context |
| Context | get_org_context_versions | List available context versions |
| Context | set_org_context | Set organization context for queries |
| CostFormation | download_costformation | Get a download link for a CostFormation definition |
| CostFormation | get_costformation_vers | List versions of a CostFormation definition |
| Optimization | get_optimize_recs | Get cost optimization recommendations |
| Optimization | get_realized_savings | Track realized savings from addressed recommendations |
| Query | get_cost_data | Query cost data with filters and groupings |
| Query | get_recent_query_history | View recent cost queries |
| Reference | get_reference_info | Get reference documentation |
| Resource | get_resource_metadata | Retrieve metadata for a single cloud resource |
| Telemetry | get_telemetry_data | Retrieve telemetry metrics |
| Telemetry | get_telemetry_streams | List available telemetry streams |
Allocations
get_available_dimensions
Lists all available Dimensions for filtering or grouping cost data, including both standard CloudZero Dimensions and custom Dimensions.
Parameters
| Parameter | Required | Description |
|---|---|---|
filter | No | Filter Dimensions by name pattern |
force_refresh | No | Bypass cache and fetch fresh data |
include_hidden | No | Include hidden Dimensions in results |
limit | No | Maximum Dimensions to return |
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
| Parameter | Required | Description |
|---|---|---|
date_range | No | Time period to scope the values |
dimension | Yes | The Dimension to get values for |
limit | No | Maximum values to return |
match | No | Filter values by pattern |
Skills: cost-comparison, custom-dimension-analysis, tag-coverage-analysis, understand-cloudzero-organization
Context
get_org_context
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 |
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.
Parameters
None.
Skills: understand-cloudzero-organization
set_org_context
Sets the organization context used for subsequent queries. Configures how cost data is interpreted and analyzed.
Parameters
| Parameter | Required | Description |
|---|---|---|
context | Yes | The context configuration to set |
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
| Parameter | Required | Description |
|---|---|---|
fqn | No | Fully qualified name of the CostFormation definition (defaults to the default definition) |
version | No | Version identifier to download (defaults to the latest version) |
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
| Parameter | Required | Description |
|---|---|---|
fqn | No | Fully qualified name of the CostFormation definition (defaults to the default definition) |
limit | No | Maximum number of versions to return (default: 10) |
Skills: Available for direct CostFormation review and export workflows
Optimization
get_optimize_recs
Retrieves cost optimization recommendations from CloudZero, including rightsizing, Reserved Instance, and Savings Plan opportunities.
Parameters
| Parameter | Required | Description |
|---|---|---|
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 | No | Filter by recommendation status |
Status values
| Value | Description |
|---|---|
addressed | Completed |
ignored | Dismissed |
in_progress | Being implemented |
not_started | Not yet acted upon |
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
| Parameter | Required | Description |
|---|---|---|
end_date | No | End date in YYYY-MM-DD format (defaults to today) |
filters | No | Filter criteria as a JSON object (for example, {"service": ["EC2"]}) |
max_partitions | No | Maximum number of partitions to return (default: 10) |
partition_by | No | Dimension to partition results by (for example, service, account, region) |
start_date | No | Start date in YYYY-MM-DD format (defaults to 30 days ago) |
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
| Parameter | Required | Description |
|---|---|---|
cost_type | No | Type of cost metric (default: real_cost) |
date_range | No | Time period to query (defaults to the last 30 days) |
filters | No | Filter criteria to narrow results |
granularity | No | Time granularity: hourly, daily, weekly, 30days, monthly |
group_by | No | Dimensions to group results by (up to 3) |
limit | No | Maximum results to return (default: 50) |
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
| Parameter | Required | Description |
|---|---|---|
reference_type | Yes | Type of reference to retrieve |
Reference types
| Value | Description |
|---|---|
cost_analyst_instructions | General cost analyst guidance |
cost_analysis_workflow | Best practices for cost analysis |
cost_types | Available cost metrics |
custom_dimensions_workflow | Working with custom Dimensions |
dimensions | Standard Dimensions |
filtering_workflow | How to filter cost data |
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
| Parameter | Required | Description |
|---|---|---|
czrn | Yes | The CloudZero Resource Name (CZRN) identifying the resource |
Skills: Available for direct resource metadata lookups
Telemetry
get_telemetry_data
Retrieves telemetry metrics from configured telemetry streams for correlating costs with operational metrics.
Parameters
| Parameter | Required | Description |
|---|---|---|
date_range | No | Time period for telemetry data (defaults to the last 30 days) |
filters | No | Filter criteria to narrow results; only Dimensions in the stream's keys can be used as filters |
granularity | No | Time granularity: hourly, daily, weekly, 30days, monthly; defaults to the stream's native granularity and cannot be finer than the stream's natural grain |
group_by | No | Dimensions to group results by; only target Dimensions in the stream's keys are valid |
limit | No | Maximum results to return (default: 50) |
stream_name | Yes | The name of the telemetry stream to query |
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
Parameter reference
Cost types
The cost_type parameter accepts the following values:
| Value | Description |
|---|---|
amortized_cost | Upfront payments spread over term |
billed_cost | As invoiced |
custom_cost | A cost calculation defined for your organization, available when CloudZero has configured one for you |
discounted_amortized_cost | Amortized with discounts |
discounted_cost | Discount amounts applied |
invoiced_amortized_cost | Recurring commitment charges amortized; upfront charges remain separate line items |
on_demand_cost | On-demand pricing |
real_cost | After all discounts (default) |
usage_amount | Usage quantities (for example, GB-hours or compute-hours) instead of cost |
Granularity options
The granularity parameter accepts:
| Value | Description |
|---|---|
30days | Fixed 30-day period breakdown |
daily | Day-by-day breakdown |
hourly | Hour-by-hour breakdown |
monthly | Month-by-month breakdown |
weekly | Week-by-week breakdown |
Omit the granularity parameter to return the total for the period with no time breakdown.
Have questions or feedback? Reach out to your account manager.
Updated 15 days ago