Troubleshooting & FAQ

Connection & auth

The client can’t connect / “failed to connect”

• Confirm the URL is exactly https://mcp.cloudquell.com/mcp (note the /mcp path; no trailing slash).
• Health check (no auth): curl -s https://mcp.cloudquell.com/health should return {"status":"ok","version":"0.4.0"}. If that fails, it’s a network/DNS issue on your side, not auth.
• Make sure your client supports remote Streamable HTTP + OAuth. If it’s stdio-only, use the mcp-remote bridge (see Connecting).

mcp.cloudquell.com doesn’t resolve

The domain is live. If it doesn’t resolve for you, it’s almost always local DNS caching or a network filter on your side — retry, flush your DNS cache, or try a different network. Nothing about your auth or org access changes.

Expired token / 401 Unauthorized

Access tokens last ~1 hour. Your client should refresh automatically; if it doesn’t, reconnect / re-authenticate the connector. For the mcp-remote bridge, clear its cached credentials (~/.mcp-auth/) and let it re-run the login. A 401 with a WWW-Authenticate: Bearer … resource_metadata=… header is the normal “log in again” signal.

“insufficient_scope”

You called a write tool with a token that carries no admin:write — normally a cak_ service key, which is read-only by design and always will be. An interactive connector token includes the scope automatically, so reconnecting is the fix there. Note that the scope alone does not permit a write — see the next two entries.

“writes_disabled_for_org: MCP writes are turned off for this organization”

This is the expected answer for a new connection. Writes are OFF by default for every organization, including existing paid ones. An org admin turns them on at Settings → Organization → AI agent access; the change takes effect on the next tool call, with no reconnect needed. Reads are unaffected either way.

An agent cannot turn this on for you — update_organization_preferences refuses the mcp_writes_enabled key on purpose. A human admin has to do it in the app.

“insufficient_role: your role is …; MCP writes require admin or super_admin”

Writes are enabled for the organization, but your CloudQuell role isn’t one that may make changes. Ask an org admin to run the change, or to raise your role. Holding admin:write does not elevate your CloudQuell role.

“org_context_unavailable”

CloudQuell couldn’t read your organization’s write setting or your role, so it refused the write instead of attempting it — the gate fails closed. Retry; if it persists, check the connection and try the change from the CloudQuell app.

“confirmation_required: pass confirm:true”

Everything else passed and the write tool was called without confirm: true. This is the last safety gate — tell the agent to proceed explicitly (e.g. “yes, create it”) so it re-sends with confirm: true.

403 Admin access required from the backend

The MCP layer let the call through, but the action still requires the right CloudQuell role server-side. Both layers check your role, and the backend is the final authority.

Data & results

A tool returns “no data” / an empty list for my org

Usually expected, not an error:

• No alert rules / no triggered alerts / no saved reports — many orgs have none configured. list_alert_rules, list_triggered_alerts, and list_saved_reports return an empty list with a note; that’s normal.
• A filter didn’t match. Service/account strings must match exactly (AmazonRDS, not “RDS”). Run get_metadata to see valid values, then retry.
• The window has no spend. Widen the date range or drop account_id/service.

query_costs says my view isn’t enabled

query_costs enables overview and detailed. For the other slices use the dedicated tool: savings → get_savings, anomalies → list_anomalies, budget status → get_budget_status, tag coverage → get_tag_coverage, allocation → get_allocation_breakdown, commitments → list_commitments. The error message names the tool to use.

The result says "truncated": true

The output exceeded the ~25k-token cap, so the tool withheld it and told you how to narrow. Add a filter (service, account_id, integration_id), lower limit, or keep response_format: "concise", then re-ask.

Numbers don’t match the dashboard

Almost always a scope/timeframe mismatch. Expand the tool call to see the exact filters and date range, confirm the currency and lastUpdated, and re-ask with tighter scope. Trust the dashboard; see Validating responses.

A percentage shows as null

The prior-period base was zero, so the percentage is undefined (not “0%”). For anomalies this is the new-service case — spend appeared where there was none.

Data looks stale

Cost data is ingested daily, not in real time — there are no intra-day figures. Check lastUpdated. If your organization has MCP writes enabled and you’re an admin, you can request a fresh pull via trigger_integration_ingest.

Org & access

I belong to multiple organizations — which one does the agent use?

Your active/primary org from your CloudQuell session. The org is not something the agent can pick. To work in another org, switch your active organization in CloudQuell and reconnect if needed.

Is this gated by my CloudQuell tier/plan?

Tool access is governed by your OAuth scope and org role. The data you see matches what your CloudQuell plan surfaces in the dashboard — if a feature isn’t on your plan, the corresponding data may be empty. Contact CloudQuell about plan coverage.

Can I use this for a scheduled / headless agent?

Yes — the interactive OAuth flow issues a long-lived refresh token, so a scheduled agent can keep running after the initial login. Dedicated service-account keys (cak_) for fully non-interactive setup are coming soon.

FAQ

Do I need to install or host anything? No — it’s a hosted remote MCP server. Add the URL to your client and sign in.

Do I need a client id or secret? No. The server provides Dynamic Client Registration; your client self-registers and uses PKCE.

Can the agent change my cloud resources? No. It reads CloudQuell’s ingested cost data, and it can make scoped CloudQuell changes (budgets, invites, channels, recommendation status) only if your organization has turned MCP writes on, you’re an admin, and the call passes confirm: true. Out of the box it can change nothing at all. It never touches your AWS resources or credentials.

Does it store my prompts? No — see Security & privacy.

Which clients are supported? Claude (claude.ai, Desktop, Code), Cursor, Goose, Codex, and any MCP client supporting remote HTTP + OAuth. See Supported clients.

Still stuck? Run MCP Inspector to list tools and isolate whether it’s a connection, auth, or data issue, then contact CloudQuell support with the tool name and inputs you used.