CloudQuell MCP Server — Overview

The CloudQuell MCP server lets an AI agent — Claude, Cursor, Goose, Codex, or any Model Context Protocol client — read and act on your organization’s cloud-cost and FinOps data in plain language. Ask “why did our RDS spend jump last week?” or “which Savings Plans expire in the next 30 days?” and the agent calls the right CloudQuell tools, scoped to your organization, and answers from your live data.

It is a remote, hosted MCP server — there is nothing to install or run. You connect your MCP client to one URL, sign in once with your CloudQuell account, and the agent gets a curated set of cost tools.

MCP / agent access is a paid feature. Using the tools requires your organization to be on a paid CloudQuell plan. A Free org can connect and see the tool list, but every tool call returns upgrade_required until you upgrade. See Access, limits & data scope.

---

What you can do

The server exposes 54 tools across the FinOps surface you already use in the CloudQuell dashboard:

• Query cost — month-to-date vs. last month, by account, by service, pivoted by product / usage-type / tag, on the accounting basis you ask for (query_costs).
• Answer “what changed?” — compare two periods (or use a week-over-week / month-over-month / year-over-year preset) and rank the movers (compare_periods).
• Project month-end spend — the same forecast the dashboard’s “Forecasted Month-End” KPI shows, org-wide and per service/account, with an honest confidence note (get_forecast).
• Find savings — rightsizing, idle resources, commitment opportunities, with dollar estimates and effort (get_savings).
• Investigate anomalies — surface month-over-month spikes and deep-dive a single service down to the resources driving it (list_anomalies, investigate_anomaly, get_resource_breakdown, get_weekly_cost_slices).
• Track budgets & forecast — budget definitions and current actual-vs-forecast status with threshold crossings (get_budgets, get_budget_status).
• Review commitments — Reserved Instances & Savings Plans utilization and upcoming expiries (list_commitments, get_expiring_commitments).
• Audit tagging & allocation — tag-coverage gaps, cost-center allocation, and the rules behind it (get_tag_coverage, get_allocation_breakdown, list_cost_centers, list_allocation_rules).
• Read saved reports & alert rules (list_saved_reports, list_alert_rules, list_triggered_alerts).
• Check whether the numbers can be trusted — a fresh / stale / degraded verdict over every provider connection, with the reason (get_data_freshness). Cost data is ingested daily, not in real time, so this is the right first call before putting a figure in front of a person.
• See the organization context — which org the agent is acting on, your role in it, who the members are, and which invites are outstanding (get_current_organization, list_organizations, list_members, list_invites).
• Make scoped changes — create a budget, send an org invite, manage notification channels, mark a recommendation applied, dismiss an anomaly, trigger an ingest (see Read-mostly + scoped writes below).

See the Tool Reference for the full, grouped list with parameters, scopes, and annotations.

The server also serves the six CloudQuell FinOps workflows as MCP prompts (weekly briefing, spend review, anomaly triage, budget guardrails, savings actions, allocation hygiene), so a client that lists prompts gets the runbooks without installing the skill pack.

Read-mostly, and writes are off by default

Of the 54 tools, 40 are reads and 14 are writes. Out of the box the writes are unreachable: every organization starts with MCP writes disabled, existing paid ones included. A newly connected agent can analyze everything and change nothing.

A write happens only when all four of these hold, checked server-side inside CloudQuell before any downstream call:

1. The token carries the admin:write scope. An interactive connector token always does (Cognito offers no per-scope consent toggle); a cak_ service key never does, and cannot.
2. The organization has MCP writes enabled — an org admin turns this on at Settings → Organization → AI agent access.
3. The caller’s org role is admin or super_admin.
4. The call passes confirm: true.

Because check 1 is true for every connector user including a viewer, it is checks 2 and 3 that actually decide. An agent cannot satisfy them for itself: enabling MCP writes over MCP is explicitly refused. This is stricter than a client-side “allow/deny” prompt. See Authentication & authorization and Security & privacy.

How it’s hosted

Aspect	Detail
Hosting	AWS Lambda + API Gateway HTTP API, region us-west-2
Transport	Streamable HTTP, stateless (JSON responses; no SSE, no session id)
Protocol SDK	@modelcontextprotocol/sdk 1.29.0 (pinned)
Auth	OAuth 2.1 + PKCE (S256) via the CloudQuell (Cognito) Hosted UI
Endpoint	https://mcp.cloudquell.com/mcp
Health check	GET https://mcp.cloudquell.com/health (public, unauthenticated)
Server version	0.4.0 · tool-surface v1 wave 3 (54 tools)

Because the transport is stateless, every request stands alone: there is no long-lived session and no server-initiated streaming. Long operations (such as async report generation, coming soon) will use a poll pattern rather than a streamed connection.

For headless / scheduled agents that can’t do a browser login, paid organizations can mint service-account (cak_) API keys from Settings → API Keys (read-only, org-scoped, valid one year). AI/LLM token spend is covered by get_ai_spend (Anthropic + OpenAI; Bedrock is excluded — it’s already in your AWS cloud spend).

Coming soon: async report generation (generate_report / get_report_job_status). See the Changelog.

Your data, your scope

The agent only ever sees data for the organization the signed-in user belongs to. Identity comes from your CloudQuell login; the server resolves your organization and role from it on every request and forwards a scoped, short-lived token to the backend. There is no cross-org access and no way for an agent to “select” another tenant it isn’t a member of. See Access, limits & data scope.

For agents

If you are an AI agent reading these docs — or pointing one at them — there is a condensed, machine-readable summary of the whole MCP surface at /mcp/llms.txt: every tool with its parameters, scopes and gotchas, the auth model, and the limits, in one plain-text file. It tracks the deployed server version and is cheaper to read than crawling this section page by page.

Next steps

1. Supported clients — pick your client.
2. Connecting — add the connector and sign in (≈5 minutes).
3. FinOps skills — install the packaged workflow runbooks (also at docs.cloudquell.com).
4. Example prompts & workflows — try it out.
5. Tool reference — the full capability list.