What is a FinOps MCP?
A FinOps MCP is a Model Context Protocol server that exposes cloud billing, allocation, and automation tools to AI assistants. Instead of pasting CUR exports into chat, the assistant calls tools likequery, create_alert, and create_report against live data.
Costory FinOps MCP adds workspace context on top of raw provider billing: , , dashboards, alerts, and saved views.
| Raw provider billing MCP | Costory FinOps MCP | |
|---|---|---|
| Data shape | Provider-native line items | Normalized, allocated spend across AWS, GCP, Azure, SaaS |
| Scope filters | Account, service, tag (if tagged) | Team, product, environment via dimensions |
| Explain cost changes | Billing deltas only | Cost diffs + deploys, metrics, and custom events |
| Actions from chat | Query only | Alerts, reports, dashboards, event annotations |
| Setup | IAM roles, local server, or Docker | One URL + OAuth |
Add Costory MCP to your Cursor / Claude / Dust
- Claude Desktop
- Claude Code
- VS Code (Copilot)
- Cursor
- Dust
- Open Claude Desktop settings
- Go to Connectors
- Click Add custom connector
- Enter Costory as the name and
https://app-api.costory.io/mcpas the URL - Click Add, then Connect
- A browser window will open. Log in with your Costory account
- Start asking about your costs

Alternative: JSON config
Alternative: JSON config
mcp-remote fallback requires Node.js to be installed.Example FinOps prompts
Explore costs
Ask questions in natural language and the assistant will query your cost data:- “How much is the platform team spending on compute this month?”
- “Show me infrastructure costs for the recommendations API, broken down by service”
- “What’s our total AI spend across Anthropic, OpenAI, and Bedrock?”
- “How much are we spending on storage?”
Compare periods
Understand how costs have changed over time:- “What’s driving the cost increase on our data pipeline this week? Any related deploys or traffic changes?”
- “Did the March 15th release affect our search service costs?”
- “Compare this week’s spend to last week for the data squad”
- “How have our compute costs changed compared to last month?”
Find information
Search across your entire Costory workspace:- “Find the saved view for the data team’s Kubernetes costs”
- “What dashboards do we have for AI spend across providers?”
- “Show me alert history related to BigQuery pipelines”
Get recommendations
The assistant can suggest what to look at:- “What dimension should I group by to explain the billing-api cost spike?”
- “Based on deploy and metric history, what should I investigate next on the data pipeline increase?”
Take action
Go beyond analysis. Create views, alerts, events, and share reports:- “Save this query as a view called ‘Recommendations API Infra Cost’”
- “Set up an alert if platform team compute costs go above $10,000 this month”
- “Log an event: deployed billing-api v2 on March 15th”
- “Send this cross-provider AI cost report to the #finops Slack channel”
FinOps MCP workflows
Each workflow below shows a natural-language prompt, the MCP tools the assistant calls, and the JSON payload shape. These examples are specific to Costory workspace context. For plugin install and additional reference examples, see the costory-plugin repository.Correlate a deploy with a cost change
Correlate a deploy with a cost change
query with period comparison, then list_events to pull deploy markers in the same window.Result: A side-by-side cost breakdown by service plus a timeline of deploys that overlapped the spike.Underlying MCP calls (JSON)
Underlying MCP calls (JSON)
querylist_eventsQuery allocated spend by team and environment
Query allocated spend by team and environment
query with a filterCel scope built from your dimensions.Result: Monthly compute spend for the platform team in production, grouped by cloud service.Underlying MCP calls (JSON)
Underlying MCP calls (JSON)
queryTrack cost per business metric
Track cost per business metric
list_metrics to resolve the metric ID, then query with a formula.Result: Unit cost trend with period-over-period comparison. See Unit Economics for the same analysis in Explorer.Underlying MCP calls (JSON)
Underlying MCP calls (JSON)
queryFind the right dimension for a spike
Find the right dimension for a spike
suggest_groupby, then query using the recommended dimension.Result: The assistant picks the most explanatory split (for example cos_k8s_namespace or cos_service_name) and drills down automatically.Underlying MCP calls (JSON)
Underlying MCP calls (JSON)
suggest_groupbyquery (using the suggested dimension)Backtest an alert before creating it
Backtest an alert before creating it
preview_alert to backtest, then create_alert with the same condition. Resolve the Slack channel via list_available_destinations.Result: A validated alert with historical firing days and a link to edit it in Costory. Requires Slack integration.Underlying MCP calls (JSON)
Underlying MCP calls (JSON)
preview_alertcreate_alert (after preview passes)Build a post-incident cost dashboard
Build a post-incident cost dashboard
create_dashboard with a scoped context and one or more widgets.Result: A shareable dashboard URL your team can reuse after incidents or cost reviews.Underlying MCP calls (JSON)
Underlying MCP calls (JSON)
create_dashboardExample conversations
Investigating a cost spike
Investigating a cost spike
- Call
get_contextto load dimensions and recent dashboards - Run
querywith a week-over-week comparison - Call
list_eventsfor deploys and provider events in the same period - Highlight likely causes with a timeline of what changed first
- Call
suggest_actionsfor follow-ups (drill deeper, set up an alert, share to Slack)
Underlying MCP calls (JSON)
Underlying MCP calls (JSON)
querylist_eventsCross-provider AI cost review
Cross-provider AI cost review
- Query AI-related spend across Anthropic, OpenAI, and AWS Bedrock
- Combine results into one total with a provider-level breakdown
- Break down the same spend by team and model
- Offer to save the view or send the report to Slack
Underlying MCP calls (JSON)
Underlying MCP calls (JSON)
queryBuilding a cost report
Building a cost report
- Query costs grouped by service for the current month
- Schedule a report via
create_report - Deliver a formatted chart to the Slack channel
Underlying MCP calls (JSON)
Underlying MCP calls (JSON)
create_reportSetting up monitoring
Setting up monitoring
- Run
preview_alertto confirm the threshold would have fired recently - Create a cost alert with
create_alert - Return a link to review and edit the alert in Costory
Underlying MCP calls (JSON)
Underlying MCP calls (JSON)
create_alertWhy Costory MCP?
Direct access to AWS CUR or a GCP MCP server gives you provider-native line items and dimensions. Costory MCP adds your Costory workspace context so you can ask higher-level cost questions and take action in the same flow.- Query spend by team, product, or feature because and are already modeled.
- Ask one question across AWS, GCP, Azure, Datadog, Anthropic, OpenAI, and Cursor instead of wiring and maintaining separate MCP servers per provider.
- Explain why costs moved by using with deploys, Datadog metrics, and provider events in the same investigation.
- Continue from saved views, dashboards, team structures, alert history, and prior investigations so your assistant has persistent workspace context.
- Connect with one URL and OAuth (no IAM credentials, Docker, or local server setup), and use it in Claude, Cursor, VS Code, or Claude Code.
- Take action directly from chat by creating alerts, saving views, logging events, and sending Cost Reports.
- Use pre-computed allocation rules and shared costs so each query starts from resolved context instead of rebuilding logic from raw CUR data.
MCP tools reference
Discovery and context
| Tool | Description | Key parameters |
|---|---|---|
get_context | Returns a workspace overview: all available dimensions (with top values), popular group-by dimensions, and recently updated dashboards. Call this first in every conversation. | None |
list_organizations | Lists all organizations the authenticated user has access to. Use when you belong to multiple organizations. | None |
search | Unified full-text search across dimension values, events, alerts, dashboards (with conditionsCel), templates, reports, virtual dimensions, budgets, and metrics. | query |
suggest_groupby | Recommends the best dimension to group costs by, given an optional scope filter and date range. | from, to, filterCel (optional) |
list_metrics | Lists all custom business metrics for the organization. Returns IDs usable in query as { type: "metric", metricId: "..." }. | None |
suggest_usage_metrics | Suggests infrastructure usage metric units (e.g. k8s_cpu_hours, network_bytes_out) relevant to a billing scope. Call before combining cost with usage in query. | filterCel (optional) |
Query and data
| Tool | Description | Key parameters |
|---|---|---|
query | Core data tool. Runs unified queries for cloud costs, custom business metrics, usage metrics, budgets, period comparisons, and formulas. Supports query types: cost, metric, usage, budget, formula. Chart types: BAR, LINE, AREA, WATERFALL, TABLE. | queries[], from, to, aggBy, compare (optional), filterCel, groupBy, limit (optional) |
get | Fetches a full resource by ID: dashboard, budget, or cost alert. Budget responses include budgetVersionId and alignment filters. Dashboard responses include widget grid positions and query configs. Alert responses include firingHistory. | id |
get_dashboard_widget_data | Runs a saved dashboard widget and returns its data without re-specifying the query config. Applies dashboard conditionsCel when the widget has extendDashboardConditions: true. | dashboardId, widgetId |
get_dashboard_widget_image | Renders a saved widget as a PNG chart, uploads to GCS, and returns the image URL (and optionally inline base64). Does not work for text/table-only widgets. | dashboardId, widgetId, includeBinaryImage (optional) |
query query types
| Type | Purpose | ID source |
|---|---|---|
cost | Cloud spend | metricId (default "cost"), currency (default "USD") |
metric | Custom business metric | list_metrics |
usage | Infra usage metric (CPU hours, network bytes, …) | suggest_usage_metrics |
budget | Budget line | get → budgetVersionId (not the parent budget ID from search) |
formula | Math over named queries | e.g. "a / b" |
Dashboards
| Tool | Description | Key parameters |
|---|---|---|
create_dashboard | Creates a new dashboard with one or more widgets. Dashboard-level context (metricId, groupBy, currency, conditionsCel, date preset) is inherited by widgets. Set extendDashboardConditions: true on widgets that should respect the dashboard filter. Returns a dashboard URL. | name, context, widgets[] |
update_dashboard | Adds, replaces, or removes widgets on an existing dashboard. Operations are applied atomically. Returns a dashboard URL. | dashboardId, operations[] |
update_dashboard operations
| Op | Description |
|---|---|
add | Append a new widget. Optional x, y, w, h for grid placement (12-column grid). |
replace | Overwrite an existing widget in place, keeping its grid position. |
remove | Delete a widget by ID. |
Alerts
| Tool | Description | Key parameters |
|---|---|---|
list_alerts | Lists all cost alerts and budget alerts with their current status and configuration. | type (cost | budget | all) |
preview_alert | Backtests a cost-alert condition against historical data before creating it. Returns firing days, per-group fires, and notification count after dedup. | queries[], condition, dedup (optional), lookbackDays (default 45) |
create_alert | Creates a cost alert that monitors queries and notifies when a condition fires. Condition examples: a > 1000, rollingSum(a, 7, DAY) > 50000. Resolve Slack/Teams channel IDs via list_available_destinations. Returns an alert URL. | name, queries[], from, to, condition, dedup, notificationChannel |
Events
| Tool | Description | Key parameters |
|---|---|---|
list_events | Lists events (deployments, business changes, provider updates) within a date range. Use to correlate cost changes with real-world events. | from, to, category (optional), tags (optional) |
create_event | Creates an event annotation on the cost timeline. Strongly recommended: attach a widget definition tying the event to the relevant chart. | name, date, description, category, tags (optional), widget (recommended) |
Reports and notifications
| Tool | Description | Key parameters |
|---|---|---|
list_available_destinations | Lists every destination the org can deliver reports or alerts to: Slack channels, Teams channels, and email. Each provider includes a connected flag. | None |
create_report | Schedules a recurring report digest via Slack, Teams, or email. Cadence: DAILY, WEEKDAYS, WEEKLY, MONTHLY. Returns a report URL. | scheduledPeriod, widget, destinations[] |
create_report widget types
| Type | Description |
|---|---|
DASHBOARD_PDF | Snapshot of an existing dashboard (ID from search). |
GRAPH_SNAPSHOT | Ad-hoc query snapshot (same config shape as query). |
TOP_FLOP | Top N gainers + bottom N losers vs the previous period. |
Organization metadata
| Tool | Description | Key parameters |
|---|---|---|
list_teams | Lists teams the current user belongs to, including each team’s scopes (pre-defined filterCel strings). | None |
list_tags | Lists all tags in the organization with usage counts across dashboards, views, explorers, and alerts. | None |
set_dashboard_tags | Sets (replaces) the full tag list on a dashboard. Pass existing tag IDs or new tag objects { name, color? }. | dashboardId, tags[] |
set_dashboard_team | Assigns a dashboard to a team, or removes it (teamId: null). | dashboardId, teamId |
delete_tag | Deletes an unused tag. Only tags with zero tagged resources can be deleted. | tagId |
Documentation
| Tool | Description | Key parameters |
|---|---|---|
search_documentation | Searches the public Costory product documentation (guides, API references, feature explanations). | query |
get_documentation_page | Retrieves the full content of a documentation page by path. Use after search_documentation. | page (e.g. "use-cases/cost-explorer") |
Agent helpers
| Tool | Description | Key parameters |
|---|---|---|
suggest_actions | Suggests follow-up actions based on investigation context (save a view, set up an alert, share to Slack, drill down, compare periods, …). Call after query or get. | hasEvents, hasDiff |
Tips
Be specific about time
Use your own names
Ask follow-ups
Multi-org support
FAQ
What is a FinOps MCP?
What is a FinOps MCP?
How is Costory FinOps MCP different from an AWS billing MCP?
How is Costory FinOps MCP different from an AWS billing MCP?
Which AI clients support FinOps MCP?
Which AI clients support FinOps MCP?
https://app-api.costory.io/mcp and authenticate via OAuth.Do I need to run a local MCP server?
Do I need to run a local MCP server?
mcp-remote bridge is available as a fallback if your client does not support HTTP transport natively.Can FinOps MCP create alerts and Cost Reports?
Can FinOps MCP create alerts and Cost Reports?
create_alert, create_report, and list_available_destinations to set up cloud cost alerts and Cost Reports directly from chat.Troubleshooting
Browser doesn't open for login
Browser doesn't open for login
mcp-remote fallback, make sure npx is available in your PATH.Claude Code: 'does not support dynamic client registration'
Claude Code: 'does not support dynamic client registration'
type: "http") rather than mcp-remote. Run /mcp in Claude Code, then select Authenticate to trigger the OAuth flow.'Not authenticated' errors
'Not authenticated' errors
/mcp and select Authenticate.'Multiple organizations' error
'Multiple organizations' error
No results from search
No results from search
