MCP Server (AI Integration)

Cloud Ctrl exposes a Model Context Protocol (MCP) server that lets AI assistants like Claude Desktop, VS Code Copilot, and Cursor query your cloud spend, budgets, recommendations, and more — without leaving the chat interface.

The MCP server provides 40 read-only tools covering spend analysis, forecasting, budgets, recommendations, reservations, and Watchdog alerts. It connects directly to the same data you see in the Cloud Ctrl UI, scoped to your tenant.

What You Can Do

With the MCP server connected, your AI assistant can:

• Query spend — "How much did we spend on Azure last month?" → calls get_spend
• Forecast costs — "What's our projected spend through December?" → calls get_forecast
• Find savings — "What are our top quick wins?" → calls get_quick_wins
• Check budgets — "Are any budgets at risk?" → calls get_budgets_at_risk
• Search recommendations — "Find idle resources" → calls search_recommendations
• Analyse anomalies — "Are there any spend spikes recently?" → calls get_spend_spikes
• Render charts — "Show me a bar chart of spend by product" → calls render_chart

All cost values are returned in your tenant's display currency, converted server-side.

Before You Begin

You need two things to connect:

1. Your tenant GUID — identifies which tenant's data the tools can access.
2. An authentication method — either OAuth (for interactive AI clients) or an API Key (for scripts and automation).

Finding Your Tenant GUID

Your tenant GUID is visible in the Cloud Ctrl URL when you're logged in. The path segment after the domain is your tenant GUID:

https://app.cloudctrl.com.au/8f3beb7a-6862-458d-b6a8-78e83325a28e/dashboard
                                  └──────────── this is your tenant GUID

You can also find it in Settings → General → Tenant ID.

Choosing an Authentication Method

Recommendation: Use OAuth for interactive AI clients — it handles token refresh automatically and doesn't require admin access to set up. Use an API Key when you need a stable credential for automation.

Connecting Your AI Client

The MCP endpoint URL is:

https://mcp.cloudctrl.com.au/mcp/<your-tenant-guid>

VS Code Copilot

Add the server to .vscode/mcp.json in your project:

{
  "servers": {
    "cloudctrl": {
      "type": "http",
      "url": "https://mcp.cloudctrl.com.au/mcp/<your-tenant-guid>"
    }
  }
}

VS Code discovers the authentication server automatically and opens a browser for you to log in. No Client ID or token pasting required.

Claude Desktop / Claude Code

Claude Code supports remote MCP over HTTP with OAuth out of the box:

claude mcp add --transport http cloudctrl "https://mcp.cloudctrl.com.au/mcp/<your-tenant-guid>"

Claude Desktop (older) uses mcp-remote as a local proxy. Install it with npm install -g mcp-remote, then add to your claude_desktop_config.json:

{
  "mcpServers": {
    "cloudctrl": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.cloudctrl.com.au/mcp/<your-tenant-guid>"]
    }
  }
}

Cursor

Cursor supports MCP servers via its settings. Add the Cloud Ctrl server URL in Settings → MCP Servers, and Cursor will handle the OAuth login flow automatically.

Other MCP Clients

Any MCP-capable client that supports Streamable HTTP transport and OAuth can connect. Point your client at the endpoint URL above. If your client doesn't support Dynamic Client Registration (DCR), you may need a pre-issued Client ID — contact support for assistance.

Connecting with an API Key

API Key authentication is the simplest method for programmatic access — no browser, no OAuth flow, no token refresh.

Creating an API Key

1. Navigate to Settings → API Keys (requires admin access).
2. Click Create Key, enter a name (e.g. "MCP automation"), and generate.
3. Copy the key immediately — it is only shown once. The full key starts with API- (e.g. API-I248X9t0fG_...); the API- prefix is part of the key.

The key authenticates as you — it inherits your tenant permissions. The key is scoped to the tenant it was created in.

Using the API Key

Pass the full key (including API- prefix) in the Api-Key header on every request:

curl -X POST "https://mcp.cloudctrl.com.au/mcp/<your-tenant-guid>" \
  -H "Api-Key: API-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

No Authorization header is needed — the Api-Key header is sufficient.

Verifying the Connection

After connecting, verify that your AI client can see the Cloud Ctrl tools:

1. List tools — your client should show ~40 tools with names like get_spend, get_budgets, get_recommendations.
2. Call get_current_date_utc — this takes no parameters and returns instantly. It confirms the connection is working.
3. Call list_subscriptions — this exercises the database path and confirms your tenant permissions are correctly enforced.

If a tool returns an error, check that:

• Your tenant GUID is correct in the URL
• Your API key hasn't expired (if using API Key auth)
• You have read access to the tenant (if using OAuth)

Available Tools

All tools are read-only — they cannot modify any data in Cloud Ctrl. Tools are tenant-scoped: they only return data for the tenant in the URL, and you must have read permission on that tenant.

Spend & Usage

Budgets & Limits

Recommendations & Savings

Reservations

Watchdog (Alerting)

Tenant Information

AI-Powered Analysis

Three sub-agent tools use an LLM to perform multi-step analysis. They take a single query parameter in natural language:

Security

• Tenant isolation: Tools only return data for the tenant in the URL. Your permissions are checked on every tool call — you cannot access another tenant's data.
• Read-only: No tool can modify, create, or delete any data in Cloud Ctrl.
• API Key security: API keys inherit your permissions and are scoped to your tenant. Treat them like passwords — store securely, revoke immediately if compromised. Keys expire after 365 days by default.
• OAuth tokens: Access tokens expire (~1 hour) and are automatically refreshed by your MCP client. No long-lived credentials are stored.
• Audit trail: Every tool call is recorded in the Cloud Ctrl audit log, including the user, tenant, tool name, and outcome.

Troubleshooting

FAQ

Is the MCP server available on all plans? The MCP server is available to all tenants. You need at least read access to connect.

Can I use the MCP server to modify data? No. All 40 tools are read-only. Write tools (e.g. creating budgets, acknowledging recommendations) may be added in a future phase.

Does the MCP server work with on-premises deployments? The MCP server is a cloud-hosted service at https://mcp.cloudctrl.com.au. It connects to the same data infrastructure as the Cloud Ctrl web UI.

How fresh is the data? Data freshness depends on your cloud provider's export schedule. Call get_import_history to see when data was last imported for each cloud account.

Can multiple users connect to the same tenant? Yes. Each user connects with their own credentials. Permissions are enforced per-user — a user with read-only access cannot perform admin actions even through the MCP server.

What happens if I revoke an API key? The key stops working within 10 minutes (the maximum cache duration). Delete the key in Settings → API Keys to revoke it immediately.