Access, limits & data scope

What an agent connected to the CloudQuell MCP server can and cannot see, and the practical limits on responses.

MCP access requires a paid plan

Using the tools is a paid CloudQuell feature (the mcp_access entitlement). A Free organization can complete the OAuth connection and list the available tools, but every tool call returns upgrade_required until the org is on a paid plan. (An organization whose subscription has ended gets subscription_ended instead.) If your agent connects successfully but each call comes back asking you to upgrade, that is the entitlement gate — upgrade the organization to unlock the tools. See Plans & billing.

What the agent can see

Everything the tools expose is your organization’s CloudQuell FinOps data:

• Cost (MTD vs. previous month, by account, by service, pivots by product/usage-type/tag).
• AI / LLM spend — direct Anthropic (Claude) and OpenAI usage, by model, token type, workspace/project, API key, or service tier (get_ai_spend). AWS Bedrock is excluded (it’s already in your AWS cloud spend).
• Savings recommendations (rightsizing, idle, commitment purchases) with estimates.
• Anomaly signals (derived from month-over-month / week-over-week movement) and per-resource breakdowns.
• Budgets and budget status (actual + forecast).
• Commitments (RIs & Savings Plans) and their utilization/expiry.
• Tag coverage, cost-center allocation, and allocation rules.
• Saved reports, alert rules, and alert firing history.
• Discovery vocabularies (service codes, tag keys, linked accounts).

This is the same data you see in the CloudQuell dashboard, surfaced through tools rather than charts.

What the agent cannot see or do

• No other organization’s data. Scope is your org only (see below).
• No raw cloud credentials or provider keys. The server reads CloudQuell’s already-ingested cost data; it never exposes your AWS keys, role ARNs, or connection secrets.
• No writes without opt-in. With the default read scope, every mutation is refused. See Authentication & authorization.
• No data the backend doesn’t compute. For example, there is no precomputed “anomaly list” — list_anomalies derives signals client-side from cost movement.

Org scoping (multi-tenancy)

The agent always operates as you, inside your organization:

• Your identity comes from your OAuth token (sub); CloudQuell resolves your organization and role from it on every request.
• The org is not a tool parameter you (or the agent) can change to a tenant you don’t belong to. There is no cross-tenant access.
• If your CloudQuell user belongs to multiple organizations, tools act on your active/primary org context. To work in a different org, switch your active organization in CloudQuell (and reconnect if needed) — the agent follows your session, it doesn’t pick the tenant.

Role-based access

OAuth scope governs read vs. write at the MCP layer; your CloudQuell role still governs what you may do downstream. Admin-only actions (org rename, invites, etc.) require an admin role on your account — admin:write scope alone does not elevate you. Non-permitted calls are rejected by the backend (403). See Authentication & authorization.

Response size, pagination & truncation

Because the transport runs on a buffered gateway, tools keep output bounded:

• response_format — every read tool defaults to concise (the few fields agents reason over). Ask for detailed only when you need the full payload; it costs more tokens.
• limit — list tools take a limit and sort the most relevant rows first (e.g. get_savings returns highest-savings-first, default 50; get_weekly_cost_slices newest-week-first, default 500).
• integration_id — narrow to one provider connection instead of the whole org.
• ~25,000-token (~100 KB) output cap. If a result would exceed it, the tool does not silently cut data — it returns a short message telling the agent how to narrow (add a filter, lower limit, switch to concise). If you see a truncated: true result, re-ask more specifically.

There is also a platform ceiling: the gateway buffers responses (~10 MB max) with a 29-second request timeout. Long work (async report generation, coming soon) will use a job-poll pattern rather than a long-held connection — consistent with the stateless transport (no server-initiated streaming or resumable sessions).

Rate limits

Treat the server as a normal, fair-use API: tools are request/response and bounded in size. Avoid tight polling loops (e.g. re-calling a status endpoint every second) — poll at a sensible interval. Excessive or abusive traffic may be throttled at the gateway. Per-tool quotas are not currently published; if you have a high-volume or scheduled use case, plan for backoff and reasonable cadence.

Data freshness

The agent sees the same numbers as the dashboard, which reflect CloudQuell’s daily cost ingestion — not real-time/hourly telemetry. Tools surface a lastUpdated timestamp where the backend provides one; use it to ground “as of when” in your answers. If data looks stale and you have the admin:write scope, trigger_integration_ingest can request a fresh pull for a connection.