Claude Code MCP

The StackSpend MCP server exposes your cost data inside Claude Code. Ask about spend, forecasts, anomalies and tasks in natural language without leaving your terminal.

What it does

The StackSpend MCP server implements the Model Context Protocol so Claude Code can read your StackSpend data as context. Once configured, you can ask about your cloud and AI costs — by provider, service, model, project, user, date range or anomaly — and get answers grounded in your actual spend.

Read tools cover spend summaries, forecasts against budget, provider health, rollups, line items, anomalies and tasks. Write tools let Claude triage an anomaly or open a task for the team — only when you explicitly ask.

Business plan required.The MCP server uses the StackSpend public API, which requires a Business plan subscription.

Setup

Create an API key

Go to Settings → API and click Create API Key. Name it something like "Claude Code MCP". New keys carry the scopes the MCP server needs:

spend:read, providers:read, rollups:read, line_items:read, anomalies:read, tasks:read
anomalies:write and tasks:write for the triage actions

Copy the key — it is shown once. Store it somewhere safe.

Add the server to Claude Code

The quickest way is the Claude Code CLI:

claude mcp add stackspend --env STACKSPEND_API_KEY=your_api_key_here -- npx -y @stackspend/mcp-server

Or add it by hand to ~/.claude.json (all projects) or .mcp.json in your project root (shared with your team):

{
  "mcpServers": {
    "stackspend": {
      "command": "npx",
      "args": ["-y", "@stackspend/mcp-server"],
      "env": {
        "STACKSPEND_API_KEY": "your_api_key_here"
      }
    }
  }
}

Tip.The same mcpServers block works in Claude Desktop, in its own config file.

Restart Claude Code

Reopen Claude Code and run /mcp. You should see stackspend listed as connected.

What you can ask

"Are we on track against budget this month?"
"What's my AWS spend this month, and is the connection healthy?"
"Which OpenAI models are most expensive?"
"Any open anomalies? What caused the biggest one?"
"Which service had the biggest cost increase last week?"
"Open a task to rightsize that instance and assign it to me."

Tools

Spend and forecasting

Tool	Scope	What it returns
get_spend_summary	spend:read	Yesterday, last 7 days, last 30 days and month-to-date, each with trend and status, for the portfolio and per provider. Includes the latest data date so you can tell stale connections from genuinely low spend.
get_forecast	spend:read	Month-end projection against budget, days until budget breach, and per-provider pace and momentum.
get_savings	spend:read	Overspend caught by resolving anomalies, this month and lifetime.
get_providers	providers:read	Connection health: last sync, last error, whether a provider needs reconnecting.

Cost data

Tool	Scope	What it returns
get_daily_rollups	rollups:read	Daily totals grouped by provider, service, category, project, user, account or model.
get_line_items	line_items:read	Raw line items, cursor-paginated, filterable on every dimension including model.

Anomalies

Tool	Scope	What it returns
get_anomalies	anomalies:read	Detected spend spikes with overrun, status, and — with source control connected — the likely contributing PR.
get_anomaly_detail	anomalies:read	The ranked change log for one anomaly: PRs and deploys with confidence, evidence and changed files.
update_anomaly_status	anomalies:write	Acknowledge, resolve, dismiss or mark false positive. Resolving or dismissing requires a note.
set_anomaly_severity	anomalies:write	Re-prioritise an anomaly.
add_anomaly_comment	anomalies:write	Comment on an anomaly thread.

Tasks

Tool	Scope	What it returns
list_tasks	tasks:read	FinOps tasks: budget reviews, optimization opportunities, savings follow-ups and model recommendations.
create_task	tasks:write	Create an optimization task, synced to a connected Jira or Linear project.
update_task	tasks:write	Transition a task through to closed.

Write tools need an explicit instruction.Claude will not close an anomaly or open a task on its own. Resolving or dismissing an anomaly requires a note, and every write is attributed to the owner of the API key.

Hosted MCP (OAuth)

For clients that need a remote MCP URL rather than a local command — Claude custom connectors, for example — StackSpend can expose the same tools over OAuth. Create an OAuth client under Settings → API, then point your client at:

https://api.stackspend.app/api/v1/mcp

Discovery metadata is served from /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource on the same host. The flow is authorization code with PKCE.

Enabled by default.Hosted MCP is on unless your deployment has switched it off. If discovery returns HOSTED_MCP_DISABLED, use the local setup above or contact support.

Prompts

Clients that support MCP prompts get four guided workflows. Each sequences the right tools and tells the model to check data freshness before trusting a number.

Prompt	What it does
cost_review	Where spend stands, what changed, and what to do — optionally for a named period
explain_anomaly	Diagnose a spike from its change log, or take the largest open one
find_savings	Reducible spend and already-logged opportunities, ranked by annualised saving
check_connections	Verify data is flowing before trusting any number

Currency

Amounts come back in your organisation's display currency, named in the response. cost and net_amount are converted; cost_usd and net_amount_usd stay in USD, so a script that already reads the USD fields keeps working.

Troubleshooting

Server not listed in /mcp — check the config file you edited is ~/.claude.json or .mcp.json, and that the block is named mcpServers.
Connection refused or timeout — set STACKSPEND_API_BASE_URL if your API is not at https://api.stackspend.app.
401 Unauthorized — the key is invalid or revoked. Create a new one.
Missing required scope — the key predates a tool. Create a new key to pick up current scopes.
Business plan required — API access is part of the Business plan.

Direct API access.The MCP server calls the same public API endpoints available to all Business plan subscribers. You can call them directly for custom integrations, scripts or dashboards.

Webhooks