MCP Server Reference
The CloudZero MCP server provides the tools that power AI Hub. Use these tools to query cost data, retrieve optimization recommendations, explore Dimensions, access telemetry, and manage organization context. 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 Role-based Access Control 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 |
|---|---|
get_optimize_recs | Optimize (View Recommendations) |
get_realized_savings | Optimize (View Recommendations) |
get_telemetry_data | Telemetry Stream Settings (View Telemetry Streams) |
get_telemetry_streams | Telemetry Stream Settings (View Telemetry Streams) |
set_org_context | Organization Administration (Modify Organization Settings) |
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 typically 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 |
| 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 |
| Reference | get_user_organizations | List accessible organizations |
| 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
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 ad-hoc 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 |
filters | No | Filter criteria to narrow results |
granularity | No | Time granularity: hourly, daily, weekly, monthly |
group_by | No | Dimensions to group results by |
include_projected_row_count | No | When true, each result row includes projected_row_count, the number of underlying cost records aggregated into that row. Present for daily, weekly, monthly, and untimed granularity; omitted for hourly. Default: false |
limit | No | Maximum results to return |
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
Retrieves the history of recent cost queries made during the session.
Parameters
| Parameter | Required | Description |
|---|---|---|
limit | No | Maximum number of queries to return |
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)
get_user_organizations
Lists all organizations the current user has access to.
Parameters
None.
Skills: understand-cloudzero-organization
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 |
granularity | No | Time granularity: hourly, daily, weekly, monthly |
stream | No | Specific 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 |
discounted_amortized_cost | Amortized with discounts |
discounted_cost | Discount amounts applied |
on_demand_cost | On-demand pricing |
real_cost | After all discounts (default) |
Granularity options
The granularity parameter accepts:
| Value | Description |
|---|---|
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.