MCP tools

Your AI client picks and calls these tools for you, so you rarely need this page to ask questions. It's here so you know what the client can do, and for building your own client.

Every tool returns JSON in a single text block. When a tool fails, it returns { "error": true, "code": "…", "message": "…" } instead. See Errors and limits.

At a glanceCopy Anchor Link

A tool your key can't use still appears in the client, but returns Missing permission when called.

Common inputsCopy Anchor Link

Several cost tools share these conventions.

• Dates are YYYY-MM-DD. A range can cover up to 366 days.
• Periods: instead of dates, pass period with a name such as last_30_days, last_month, this_month, last_quarter, this_year, Q2 2026, May 2026, or 2026. Explicit dates win over period.
• Recent days: the bill usually runs a day behind, so an end date of today or later becomes the last complete day. The response says when this happened.
• Providers: aws, azure, gcp, oracle, snowflake, databricks, openai, github, k8s. Leave it out to cover every provider your key can see.
• Currency: amounts are in your organisation's display currency. get-currency-in-use tells you which.

OrganisationCopy Anchor Link

get-customer-infoCopy Anchor Link

Your organisation's name, the providers the key can see, and the display currency.

Inputs: none.

Returns: customer_id, name, cloud_providers (the providers within the key's scope), currency, currency_note (when costs are in mixed currencies), and sso_warning.

get-user-profileCopy Anchor Link

What the key can access: providers, accounts, and features.

Inputs: none.

Returns: is_admin, cloud_providers, accessible_accounts (per provider, "all" or a list of account IDs), and features. email is null for access keys.

get-currency-in-useCopy Anchor Link

The currency cost amounts are reported in.

Inputs: none.

Returns: currency (for example USD), and currency_note when no display currency is set and the bill holds several currencies (currency is then MIXED).

CostCopy Anchor Link

list-cost-dimensionsCopy Anchor Link

Every dimension you can group or filter cost by, with an example value. Clients call this first so they use real dimension names.

Inputs: none.

Returns:

• dimensions: billing columns and tag families. Each has an id (what other tools take), the providers that have it, a kind (SCALAR, TAG_KEY, or MACRO), a cardinality (LOW or HIGH), and an example value.
• business_dimensions: your Dimension Studio dimensions, with IDs like alloc:<allocation>:<column>.
• has_allocation: whether your organisation has published allocations.

See Dimensions for what each dimension means.

get-cost-by-dimensionCopy Anchor Link

The main cost tool. Cost broken down by up to three dimensions, as a total or as a trend over time, with filters.

You must pass dimension or dimensions. Date words such as date or month aren't dimensions; use granularity for time.

Example input: EC2 cost by account for last month.

{
  "dimension": "sub_account_name",
  "period": "last_month",
  "filters": { "service_name": { "type": "include", "values": ["Amazon Elastic Compute Cloud"] } }
}

Returns:

{
  "dimension": "sub_account_name",
  "currency": "USD",
  "period": { "start": "2026-09-01", "end": "2026-09-30" },
  "granularity": "total",
  "cost_type": "net_amortized",
  "grand_total": 48210.55,
  "total_rows": 12,
  "truncated": false,
  "breakdown": [
    { "value": "prod-main", "display_name": "prod-main", "cost": 31002.1, "percentage": 64.3 },
    { "value": "data-platform", "display_name": "data-platform", "cost": 9870.4, "percentage": 20.5 }
  ],
  "unallocated_cost": 0,
  "_metadata": { "providers_queried": ["aws"], "rows_returned": 12, "total_rows_available": 12 }
}

• With several dimensions, each row has groups (dimension → value) instead of value.
• With a trend granularity, the response has a trend of { date, cost } points.
• When truncated is true, fetch the next page. A final Other (N more) row keeps the rows adding up to grand_total.
• _metadata explains anything adjusted: providers dropped by a filter, a clamped end date, or a repaired filter.

get-dimension-valuesCopy Anchor Link

The real values of a dimension, so a filter uses values that exist. Leave dimension out to get every low-cardinality dimension at once.

Returns: values_by_provider, one entry per provider with its values (and its own error if that provider failed). Without dimension: by_dimension, one entry per dimension.

investigate-spikeCopy Anchor Link

One service's daily cost over a window, compared with the period of the same length just before it.

Returns: total_cost, prior_period_cost, pct_change (null when the prior period was zero), currency, and daily ({ date, cost } points). A partial service name returns the names that contain it.

get-newly-spawned-resourcesCopy Anchor Link

Resource IDs that had cost in a window, most expensive first, up to 500. Useful for finding what's behind a spike.

Returns: resource_count, resources (IDs), and truncated when there were more than 500.

get-rca-hierarchyCopy Anchor Link

Your organisation's saved drill-down paths for investigating a spike, for example provider → service → account → region.

Inputs: none.

Returns: views, each with a name, cloud_providers, a principal_dimension, and its drill_down_hierarchy. An empty list if none are set up.

Atlas inventoryCopy Anchor Link

These tools read Atlas: what's running now, polled every few hours. Atlas costs are in USD, amortised, over the last 30 days.

Filtering resourcesCopy Anchor Link

atlas-summary and atlas-find-resources take the same filter:

Fields for where include region, account, state, owner, signal, cost, age, pricing, machine, platform, engine, size, vpc, tag:<key>, and more. signal takes Idle, Underused, Orphaned, Stopped, Untagged, or None. An unknown field returns the list of valid ones.

Example: idle EC2 instances costing over $50 a month.

{
  "services": ["ec2"],
  "where": [
    { "field": "signal", "values": ["Idle"] },
    { "field": "cost", "min": 50 }
  ]
}

atlas-summaryCopy Anchor Link

How many resources you have and what they cost, by service, with untagged, orphaned, and stopped counts. Optionally broken down by any field.

Takes the filter, plus:

Returns: resources, cost_30d, resources_change_7d_pct, untagged (count, cost, and tag coverage), orphaned, stopped, by_service, group (when group_by is set), inventory_polled_at, and billed_through.

atlas-find-resourcesCopy Anchor Link

Resources that match a filter, most expensive first.

Takes the filter, plus:

Returns: matched (total count and cost), shown, and resources, each with id, name, service, provider, account, region, state, signals, owner, size, age_days, and cost_30d.

atlas-resourceCopy Anchor Link

Everything Atlas knows about one resource.

Returns: resource (identity, account, region, state, age, signals), cost (30-day cost, on-demand equivalent, commitment coverage), recommendation, owner, tags and missing_tags, attributes, utilization (14 days of CPU, memory, and other metrics as p50, p95, and max), recent_changes, and related resources.

atlas-changesCopy Anchor Link

Resources added, removed, or changed, with the monthly cost effect. Atlas keeps 30 days of changes.

Returns: net (total changes and monthly cost delta, split into added, removed, and changed), summary, and by_change_type, each listing its changes with at, resource_id, name, service, account, owner, what changed, and cost_delta_per_month.

CanvasesCopy Anchor Link

list-canvasesCopy Anchor Link

The canvases the key can see. Names only; no widgets or figures.

Returns: canvases, each with id, name, owner, updated_on, and how it's shared (org_visible, shared_with_me), plus count.

get-canvasCopy Anchor Link

One canvas's settings and what each widget shows. It returns no cost figures and no filter values.

Returns: id, name, settings, and widgets, each with its kind, title, chart_type, group_by, granularity, and the filter keys it uses.

DatasetsCopy Anchor Link

list-datasetsCopy Anchor Link

Your organisation's datasets: tables loaded next to cloud cost, such as LLM usage or revenue.

Inputs: none.

Returns: datasets, each with id, name, status, rows, the dates it covers, its measures (number columns, each with a unit) and its dimensions (text columns).

get-dataset-column-valuesCopy Anchor Link

The real values of one text column in a dataset, most frequent first.

Returns: values and count. An unknown dataset or column returns an empty list with a note, not an error.

BudgetsCopy Anchor Link

Amounts are in USD for the current budget period.

find-budgetsCopy Anchor Link

The budgets you can see, worst first, with forecast and severity.

Returns: total, shown, and budgets, each with budgetId, name, owner, manager, amount, spent, forecast, forecastPct, breachDate, severity (On track, Watch, At risk, or Over budget), and the main driver.

investigate-budgetCopy Anchor Link

One budget in depth: what's moving, recent alerts, and any open increase request.

Returns: budget, services (the top 8, each with this period's spend and the last 7 days against the 7 before), recentAlerts, and openIncreaseRequest.

prepare-budget-increaseCopy Anchor Link

Whether you can request a budget increase, and a suggested amount. It never raises the request; you do that from the budget in OpsLyft.

Returns: canRequest (and the reason if not), currentAmount, suggestedAmount (the forecast plus 10% headroom, rounded), managerEmail, and any openRequest.

Allocations (Dimension Studio)Copy Anchor Link

These tools read and edit the allocations that tag and split cost into your business dimensions. They need a key with Admin on all spend.

Changes always go into a draft. Nothing reaches your published allocation until you publish the draft, and publishing takes two calls so the client can show you what will change first.

ReadCopy Anchor Link

EditCopy Anchor Link

Edit tools are limited to 10 calls a minute per key. Changes made with a key are recorded against the key's creator.

SessionCopy Anchor Link

The server asks clients to call these around each question so a conversation can be followed end to end. They don't return data and aren't rate-limited.

Both return { "acknowledged": true, "session_id": "…" }.

RelatedCopy Anchor Link

• MCP: connect a client
• Access keys
• Errors and limits