MCP Plugin for AI Agents

The CloudBurn plugin gives your AI agent a local MCP server and a skill for reviewing AWS infrastructure. The server uses the CloudBurn SDK to run the same cost optimization rules as the CLI. It exposes four read-only tools for scanning IaC, discovering live resources, checking discovery setup, and listing rules.

Prerequisites

• Node.js 24 or later, with npx on PATH in the environment that starts your agent.
• A client that supports local MCP servers over stdio.
• For live discovery: AWS credentials and AWS Resource Explorer. IaC scans and rule listing need no AWS credentials.

The MCP server runs independently of the CLI. The plugin's skill can fall back to the CLI when MCP tools are unavailable; that fallback requires a CLI installation.

Install the plugin

The plugin bundles the MCP server with a skill that guides the agent through scans and findings. Its generated configuration pins the server to the plugin's released version.

Claude Code

claude plugin marketplace add towardsthecloud/cloudburn-plugin
claude plugin install cloudburn@towardsthecloud

Codex

codex plugin marketplace add towardsthecloud/cloudburn-plugin
codex plugin add cloudburn@towardsthecloud

Skill only

For agents supported by skills.sh, install just the skill:

npx skills add towardsthecloud/cloudburn-plugin

This installs the skill without registering the MCP server. Install the server separately or use the CLI fallback.

Install only the MCP server

Register the server directly if you want the tools without the plugin's skill:

# Claude Code
claude mcp add cloudburn -- npx -y @cloudburn/mcp

# Codex
codex mcp add cloudburn -- npx -y @cloudburn/mcp

For clients that use an mcpServers configuration, add:

{
  "mcpServers": {
    "cloudburn": {
      "command": "npx",
      "args": ["-y", "@cloudburn/mcp"]
    }
  }
}

Use your client's configuration format if it differs. On first use, npx downloads @cloudburn/mcp and its dependencies from npm.

Run your first scan

Ask the agent to list CloudBurn's IaC rules, then scan an absolute path:

List CloudBurn's IaC rules, then scan /absolute/path/to/iac for AWS cost issues.
Explain each finding and link to its rule documentation.

The agent can call list_rules with { "sources": ["iac"] } and scan_iac with:

{
  "path": "/absolute/path/to/iac",
  "configPath": "/absolute/path/to/project/.cloudburn.yml"
}

Replace the paths with your own. Omit configPath if you have no configuration file. Scan results include findings grouped by provider and rule, source locations when available, suppressed findings, and parse diagnostics. See the JSON output reference for the scan result shape.

Tool reference

Scan arguments

scan_iac requires path, an absolute file or directory path. Both scan_iac and discover accept these optional arguments:

Selection arrays must contain at least one value. Without explicit selection or configuration, scans use the AWS Core preset. See rule selection for how configuration and overrides combine.

Paths must be absolute because the server's working directory depends on the agent host. Without configPath, configuration discovery starts from that working directory, which may differ from the scanned project's directory. Pass an explicit path to use the project's settings reliably. In CI, implicit configuration discovery is skipped.

The MCP server rejects custom configuration filenames with INVALID_ARGUMENT. Rename a custom file to .cloudburn.yml or .cloudburn.yaml before passing it through MCP.

Discovery arguments

discover also accepts:

Clients that request progress receive notifications for catalog loading, dataset collection, and rule evaluation. Rule progress is provisional; use the final result to assess findings and coverage.

Rule listing arguments

list_rules accepts optional services and sources arrays and a severity filter. sources values are iac and discovery; severity is high, medium, or low. Filter arrays must contain at least one value.

discovery_status takes no arguments.

Live AWS discovery

The server uses the standard AWS credential chain of the process that starts it. Set AWS_PROFILE and AWS_REGION in that environment and ensure the session is valid before asking the agent to discover resources.

Set up AWS Resource Explorer through the CLI first:

npx -y cloudburn discover init

This setup command can create or update Resource Explorer resources. The MCP server does not expose it; all four MCP tools remain read-only. Follow Resource Explorer setup for permissions and setup choices.

Ask the agent to run discovery_status, then discover for your region. Live scans require the read permissions used by the selected rules. See AWS credentials and the discovery reference.

Discovery shares the CLI's per-user evidence cache at $XDG_CACHE_HOME/cloudburn/evidence when XDG_CACHE_HOME is absolute, or ~/.cache/cloudburn/evidence otherwise. Use cache: "refresh" to recollect evidence or cache: "off" to bypass it.

Errors and data handling

Tool failures return MCP isError: true, with JSON text in this shape:

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "path must be an absolute path; received \"./iac\"."
  }
}

Error messages are redacted before reaching the agent. If credentials are missing or expired, refresh the session used by the server's host process. If discovery setup is incomplete, check discovery_status and complete the CLI setup.

The server runs locally and sends no CloudBurn telemetry. Live discovery calls AWS APIs and caches collected evidence locally. Tool results are passed to your MCP client; that client's handling of results depends on its own configuration and data policy.

What's next