Using the CloudFix MCP Server with AI Assistants

What this is

The CloudFix MCP (Model Context Protocol) server lets you connect an AI assistant — Claude Code, Claude Desktop, Cursor, or any other MCP-compatible client — directly to your CloudFix tenant. Once connected, you can ask the assistant questions like “What are my top cost optimization recommendations?” or “Summarize recommendations by finder type” and it queries live CloudFix data on your behalf, instead of you copying numbers out of the dashboard by hand.

The MCP server is read-only. It cannot fix, postpone, reject, or schedule anything in your account — all of that still happens through the CloudFix UI or the CloudFix API.

Who this guide is for

FinOps or DevOps engineers who want to query CloudFix recommendations conversationally from an AI assistant
CloudFix admins who need to enable, restrict, or issue access for MCP on their tenant
Anyone already comfortable with the CloudFix API who wants an AI-assistant front end to the same data

What tools are available

The MCP server exposes the following tools to your AI assistant. Which ones are actually available on your tenant depends on your account type and your MCP settings (see Tool availability and limits below).

list_recommendations — paginated recommendations, filterable by finder, status, account, region, organizational unit, and date range
get_recommendation_details — full details for a single recommendation by ID, including its parameters
get_recommendation_report — the finder-generated analysis report behind a specific recommendation
get_recommendations_summary — aggregated counts and savings grouped by finder/optimization type, useful for prioritization and leadership reporting
get_ec2_price — looks up the price of a specific EC2 instance type (region, platform, tenancy, pricing model) from the CloudFix EC2 pricing snapshot
find_ec2_instances — searches the EC2 instance catalog by vCPU, RAM, GPU, processor, family/size, or price ceiling, ranked by price — useful for “what’s the cheapest instance that meets this spec” questions
get_resource_validations — the underlying validation-pipeline results (metrics, thresholds, pass/fail) behind a recommendation. This tool is reserved for internal use and is not available on customer (external) tenants; it does not appear in your tool list even if you try to enable it.

All tools are scoped to your tenant only — a token issued for your account can never see another tenant’s data.

Prerequisites

An AI assistant that supports remote MCP servers over Streamable HTTP — Claude Code 2.1+, Claude Desktop (via the mcp-remote bridge), Cursor, or another MCP-compliant client
A CloudFix user with permission to view Settings → MCP, and (to generate a token yourself) permission to create API tokens

Connect from CloudFix Settings (recommended)

The fastest way to connect is from inside the CloudFix UI:

Sign in to CloudFix and go to Settings → MCP.
If MCP is disabled for your tenant, ask an admin to turn on the master Enable MCP toggle. (It is on by default for new tenants.)
Click to generate a Reader-role API token for MCP use. The token is shown in full exactly once — copy it before closing the dialog. If you lose it, generate a new one; the old one can be revoked.
Pick your client tab (Claude Code, Cursor, or Claude Desktop) and either copy the ready-made JSON configuration block into your client’s config file, or copy the one-line installer command shown at the bottom of the page and run it in your terminal:

curl -fsSL https://app.cloudfix.com/install-mcp.sh | API_KEY=cft_<your-token> sh

The installer configures the CloudFix MCP server for Claude Code automatically (it requires the claude CLI to already be installed). Note that API_KEY=... must appear on the sh side of the pipe as shown — putting it before curl only scopes it to curl and the script will report a missing API key.

Connect manually

If you’d rather not run the installer, add the server to your client’s MCP configuration directly. Replace cft_<your-token> with a token generated from Settings → MCP or Settings → API Tokens (Reader role is sufficient).

Claude Code

One-liner (writes to your user config, available across all projects):

claude mcp add --transport http cloudfix-recommendations \
  https://mcp.app.cloudfix.com/mcp \
  --header "Authorization: Bearer cft_<your-token>"

Or add it to .mcp.json to scope it to one project:

{
  "mcpServers": {
    "cloudfix-recommendations": {
      "type": "http",
      "url": "https://mcp.app.cloudfix.com/mcp",
      "headers": {
        "Authorization": "Bearer cft_<your-token>"
      }
    }
  }
}

Use "type": "http" — Claude Code 2.1 and later support Streamable HTTP natively. "type": "url" is not a valid value.

Cursor

Add this to ~/.cursor/mcp.json (or a project-level .cursor/mcp.json):

{
  "mcpServers": {
    "cloudfix-recommendations": {
      "url": "https://mcp.app.cloudfix.com/mcp",
      "headers": {
        "Authorization": "Bearer cft_<your-token>"
      }
    }
  }
}

Claude Desktop

Claude Desktop only launches local (stdio) servers, so the config bridges to the CloudFix MCP server using the mcp-remote npm package. Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "cloudfix-recommendations": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.app.cloudfix.com/mcp",
        "--header",
        "Authorization: Bearer cft_<your-token>"
      ]
    }
  }
}

On Windows, if you see 'C:\Program' is not recognized, run npm install -g mcp-remote first and use "command": "mcp-remote" (without npx) to avoid the spaces-in-path issue.

Verify the connection

In Claude Code, run /mcp and confirm cloudfix-recommendations shows as connected. In Claude Desktop or Cursor, restart the app after saving the config, then try a prompt such as:

List my CloudFix recommendations sorted by annual savings

Summarize my CloudFix recommendations by finder type and show total potential savings

What's the cheapest Graviton instance with at least 8 vCPUs and 32 GB RAM in us-east-1?

Authentication and token scope

The MCP server authenticates with the same cft_-prefixed API tokens used by the rest of the CloudFix API. Send the token as Authorization: Bearer cft_<token> (the server also accepts the api-token scheme).
A token minted with the Reader role is sufficient for every MCP tool — MCP is read-only, so higher-privilege roles (ResourceManager, RunbookManager) aren’t required for it.
Tokens are tenant-scoped: a token can only ever see and query the tenant it was issued for.
Tokens generated for MCP are the same underlying object as tokens generated from Settings → API Tokens — they’re interchangeable and both show up in your token list. You can revoke an MCP token at any time from Settings → API Tokens; revoking it immediately disconnects any AI assistant using it.
MCP does not use OAuth; there is no browser-based sign-in step for the assistant itself — the token is the only credential.

Tool availability and limits

Read-only. No MCP tool can trigger a fix, postpone a recommendation, mark something manually fixed, or create a change request. Use the CloudFix UI or the API for those actions.
Master on/off switch. An admin can disable MCP entirely for the tenant from Settings → MCP. When it’s off, every MCP call is rejected regardless of whether the token is otherwise valid.
Per-tool toggles. From the same Settings → MCP page, an admin can turn individual tools on or off for the tenant. A disabled tool is removed entirely from what your AI assistant sees when it lists available tools — it won’t just fail when called, the assistant won’t know it exists.
get_resource_validations is internal-only. This tool is hard-locked off for customer (external) tenants and cannot be turned on from Settings — it simply doesn’t appear as an available tool. It exists for CloudFix support engineers debugging recommendation logic on your behalf.
Pagination. list_recommendations returns up to 100 results per page (default 25); find_ec2_instances returns up to 100 per page (default 50). Ask your assistant to page through results rather than requesting everything at once for large accounts.
No push notifications. MCP is request/response only — it won’t alert you when new recommendations appear. Use webhooks or email integrations for that.

Frequently asked questions

Which AI assistants work with CloudFix MCP?

Any client that speaks the MCP Streamable HTTP transport. CloudFix documents Claude Code, Claude Desktop, and Cursor above; other MCP-compliant clients that support a Bearer-token Authorization header should work the same way — point them at the same URL and header.

Can I use MCP to trigger a fix?

No. MCP is intentionally read-only. Use the CloudFix UI, or the API’s /api/v3/recommendations/postpone, /api/v3/recommendations/manual-fix, or /api/v3/create-change-requests endpoints, to take action on a recommendation.

Do I need a separate token just for MCP?

No, but it’s good practice. Any valid API token with at least Reader access works with MCP, and a token generated from the MCP tab is the same kind of object as one from the API Tokens tab. Using a dedicated token per assistant makes it easy to revoke access for just that integration later without affecting anything else using your other tokens.

My assistant can’t connect — what should I check?

Confirm the URL is exactly https://mcp.app.cloudfix.com/mcp (production) — note the /mcp path suffix.
Confirm the header is Authorization: Bearer cft_<token> with no extra whitespace, and that the token hasn’t been revoked.
Confirm MCP is enabled for your tenant in Settings → MCP — a valid token still gets rejected if the tenant-level master switch is off.
If a specific tool seems to be missing, check whether it’s been disabled in Settings → MCP, or whether it’s get_resource_validations, which is not available on customer tenants.

How fresh is the data MCP returns?

MCP queries the same live recommendation data as the CloudFix dashboard and the v3 API — there is no separate cache or delay layer specific to MCP.

Choose files or drag and drop files

Tags:

Was this article helpful?

Yes

Bill Gleeson
Posted
Updated