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 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-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. - 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.
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.
| Tool | Required permission set | Required scope |
|---|---|---|
download_costformation | Dimension Definition Settings (View Dimension Definitions) | cost-contexts:get-definition-download-link |
get_container_usage | Kubernetes Cluster Details (View Kubernetes Cluster Details) | container:get_usage |
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_generated_context | Organization Administration (Modify Organization Settings) | czca-server:set-org-context |
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 context: custom instructions and generated context |
| Context | get_org_context_versions | List available context versions |
| Context | set_generated_context | Replace the generated context that /init derives from query history |
| Context | set_org_context | Replace the custom instructions that agents follow |
| CostFormation | download_costformation | Get a download link for a CostFormation definition |
| CostFormation | get_costformation_vers | List versions of a CostFormation definition |
| Kubernetes | get_container_usage | Get Kubernetes CPU and memory usage versus requests |
| 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
Organization context is the guidance every agent reads at the start of a cost analysis session. It has two sections with different owners:
| Section | Written by | What it holds |
|---|---|---|
| Custom Instructions | You, with set_org_context or by asking the agent | Rules agents must follow: business rules, Dimension preferences, team structures and cost ownership, cost allocation policies |
| Generated Context | The /init prompt, with set_generated_context | What /init derives from your recent query history: Dimension definitions, common workflows, team structures, cost allocation patterns |
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
| Parameter | Required | Description |
|---|---|---|
version | No | Specific context version to retrieve (defaults to the latest) |
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
| Parameter | Required | Description |
|---|---|---|
generated | Yes | The complete generated context. Replaces the current Generated Context section; Custom Instructions are left unchanged |
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
| Parameter | Required | Description |
|---|---|---|
context | Yes | The complete custom instructions. Replaces the current Custom Instructions section; Generated Context is left unchanged |
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
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
| Parameter | Required | Description |
|---|---|---|
date_range | No | Time period to query (defaults to the last 30 days) |
filters | No | Filter criteria as a dict mapping a dimension to the values to include, for example {"k8s_workload": ["checkout-api"]} |
partition_by | Yes | Kubernetes entity to key the results by |
Partition values
| Value | Description |
|---|---|
k8s_cluster | Key results by cluster |
k8s_namespace | Key results by namespace |
k8s_workload | Key results by workload |
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.
Skills: Available for direct Kubernetes rightsizing lookups
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 6 days ago