KloudHub MCP Documentation

List Cloud Accounts

List all connected AWS cloud accounts. Returns account names, regions, AWS account IDs, and validation status. Cloud credentials are never included.

Returns

List of accounts, each with id, name, aws_account_id, region, provider, and status.

Example

list_cloud_accounts()

Example Response

[
  {
    "id": "a1b2c3d4-...",
    "name": "Production AWS",
    "aws_account_id": "123456789012",
    "region": "ap-south-1",
    "provider": "aws",
    "status": "validated"
  }
]

List Klouds

List all infrastructure blueprints for the authenticated user.

Returns

List of Klouds with id, name, status, created_at, and metadata.

Example

list_klouds(status="completed")

Example Response

[
  {
    "id": "k1b2c3d4-...",
    "name": "prod-vpc",
    "status": "completed",
    "created_at": "2026-04-12T10:30:00Z"
  }
]

Get Kloud Details

Get detailed information about one or more Kloud blueprints. Includes name, status, tags, validation status, and generation timestamps.

Returns

Full Kloud metadata. Single ID returns dict, multiple IDs return list.

Example

get_kloud("k1b2c3d4-...")

Example Response

{
  "id": "k1b2c3d4-...",
  "name": "prod-vpc",
  "status": "completed",
  "description": "VPC with 2 public and 2 private subnets",
  "tags": ["vpc", "networking"],
  "source_type": "ai_generated",
  "created_at": "2026-04-12T10:30:00Z"
}

Create Kloud

Generate a new infrastructure blueprint using AI. This is async. Poll get_kloud(kloud_id) until status is 'completed'.

Returns

kloud_id and status with _next polling hints.

Example

create_kloud(
  name="prod-vpc",
  description="VPC with 2 private and 2 public subnets across 2 AZs, with NAT gateway"
)

Example Response

{
  "kloud_id": "k1b2c3d4-...",
  "status": "generating",
  "_next": {
    "poll_status": "get_kloud('k1b2c3d4-...')",
    "then_deploy": "deploy_kloud(kloud_id='k1b2c3d4-...', cloud_account_id='...')"
  }
}

List Deployments

List deployment history with status, kloud name, and resource change counts.

Returns

List of deployment summaries.

Example

list_deployments(status="deployed", limit=5)

Example Response

[
  {
    "id": "d1-...",
    "status": "deployed",
    "kloud_name": "prod-vpc",
    "resources_added": 12,
    "deployed_at": "2026-04-12T11:00:00Z"
  }
]

Deploy Kloud

Deploy a Kloud to AWS using Terraform. Always confirm with the user before calling. Async operation. Poll get_deployment_status until 'deployed' or 'failed'.

Returns

deployment_id with polling hints.

Example

deploy_kloud(
  kloud_id="k1b2c3d4-...",
  cloud_account_id="a1b2c3d4-...",
  region="ap-south-1"
)

Example Response

{
  "deployment_id": "d1-...",
  "status": "initializing",
  "_next": {
    "poll_status": "get_deployment_status('d1-...')",
    "get_logs": "get_deployment_logs('d1-...')"
  }
}

Get Deployment Status

Get current status. Values: pending, planning, planned, applying, deployed, failed. Supports batch.

Returns

Status, plan summary, resource counts. On completion, includes _next hints.

Example

get_deployment_status("d1-...")

Example Response

{
  "id": "d1-...",
  "status": "deployed",
  "resources_added": 12,
  "resources_changed": 0,
  "resources_destroyed": 0,
  "_next": {
    "get_details": "get_deployment_details('d1-...')",
    "get_logs": "get_deployment_logs('d1-...')"
  }
}

Get Deployment Logs

Fetch raw Terraform plan/apply output. Logs are sanitized at source. No credentials included.

Returns

Raw Terraform log output as string.

Example

get_deployment_logs("d1-...", log_type="plan")

Example Response

"Terraform will perform the following actions:\n\n  # aws_vpc.main will be created\n  + resource \"aws_vpc\" \"main\" { ... }\n\nPlan: 12 to add, 0 to change, 0 to destroy."

Get Deployment Details

Full deployment view: Terraform outputs (vpc_id, public_ip, etc.), plan summary, error details, timestamps, and state metadata.

Returns

Complete deployment detail with terraform_outputs, timestamps, and error info.

Example

get_deployment_details("d1-...")

Example Response

{
  "id": "d1-...",
  "status": "deployed",
  "terraform_outputs": {
    "vpc_id": "vpc-0abc123",
    "public_subnet_ids": ["subnet-1", "subnet-2"]
  },
  "deployed_at": "2026-04-12T11:05:00Z"
}

Cancel Deployment

Cancel a stuck or unwanted deployment. Use when a deployment is stuck in pending/planning/applying state.

Returns

Updated deployment status.

Example

cancel_deployment("d1-...")

Example Response

{ "deployment_id": "d1-...", "status": "cancelled" }

Destroy Deployment

Destroy the AWS infrastructure. IRREVERSIBLE. Runs terraform destroy. Always confirm with user first. Only works on deployed/failed deployments.

Returns

destroy_deployment_id for status polling.

Example

destroy_deployment("d1-...")

Example Response

{
  "destroy_deployment_id": "d2-...",
  "parent_deployment_id": "d1-...",
  "status": "destroying",
  "_next": {
    "poll_status": "get_deployment_status('d2-...')"
  }
}

List Cloud Scans

List previous scans. Check if a recent scan exists before starting a new one.

Returns

List of scans with scan_id, status, total_resources, total_monthly_cost, created_at.

Example

list_scans(cloud_account_id="a1-...", limit=5)

Example Response

[{ "scan_id": "s1-...", "status": "completed", "total_resources": 47, "total_monthly_cost": 234.50 }]

Start Cloud Scan

Start a full AWS resource discovery scan. Discovers EC2, S3, RDS, Lambda, VPC, etc. and calculates costs. Async.

Returns

scan_id with polling hints.

Example

start_cloud_scan(cloud_account_id="a1-...")

Example Response

{ "scan_id": "s1-...", "status": "pending", "_next": { "poll_status": "get_scan_status('s1-...')" } }

Get Scan Status

Check scan progress. Status: pending, scanning, completed, failed, cancelled.

Returns

Status, total resources found, total monthly cost, regions scanned.

Example

get_scan_status("s1-...")

Example Response

{ "status": "completed", "total_resources": 47, "total_monthly_cost": 234.50, "regions": ["ap-south-1", "us-east-1"] }

Get Scan Resources

Get discovered AWS resources. Credentials are never included.

Returns

List of resources with type, name, region, state, and monthly cost.

Example

get_scan_resources("s1-...", service="EC2", limit=10)

Example Response

[{ "resource_id": "i-0abc123", "service": "EC2", "name": "web-server-1", "region": "ap-south-1", "state": "running", "monthly_cost": 45.20 }]

Get Scan Costs

Cost breakdown by service and region from a completed scan.

Returns

List of {service, region, monthly_cost_usd} and total_monthly_usd.

Example

get_scan_costs("s1-...")

Example Response

{ "costs": [{ "service": "EC2", "region": "ap-south-1", "monthly_cost_usd": 120.50 }], "total_monthly_usd": 234.50 }

Get Cost Comparison

Compare current month-to-date spend vs previous month. Includes percentage change and full-month forecast.

Returns

mtd_cost_usd, last_month_same_period_usd, change_pct, forecast_usd.

Example

get_cost_comparison("s1-...")

Example Response

{ "mtd_cost_usd": 115.50, "last_month_same_period_usd": 98.20, "change_pct": 17.6, "forecast_usd": 234.50 }

Get Cost Trend

Historical AWS cost data from Cost Explorer, broken down by month and service.

Returns

Monthly cost breakdown with per-service detail.

Example

get_cost_trend("s1-...", months=6)

Example Response

{ "months": [{ "month": "2026-03", "total": 210.30, "by_service": { "EC2": 120.50, "RDS": 45.00 } }] }

List Waste Analyses

List previous waste analyses. Check for existing results before starting a new analysis.

Returns

List with analysis_id, status, total_findings, total_estimated_savings, created_at.

Example

list_waste_analyses(cloud_account_id="a1-...")

Example Response

[{ "analysis_id": "w1-...", "status": "completed", "total_findings": 8, "total_estimated_savings": 156.30 }]

Start Waste Analysis

Start waste detection. Analyzes 14 days of CloudWatch metrics to find resources that can be rightsized, stopped, or terminated. Async.

Returns

analysis_id with polling hints.

Example

start_waste_analysis(cloud_account_id="a1-...")

Example Response

{ "analysis_id": "w1-...", "status": "pending", "_next": { "poll_status": "get_waste_status('w1-...')" } }

Get Waste Analysis Status

Check waste analysis progress. Status: pending, analyzing, completed, failed, cancelled.

Returns

Status and progress percentage.

Example

get_waste_status("w1-...")

Example Response

{ "status": "completed", "progress": 100 }

Get Waste Findings

Get waste findings sorted by estimated savings. Each finding includes resource details, savings estimate, and remediation recommendation.

Returns

List of findings with resource_id, service, severity, estimated_monthly_savings, recommendation.

Example

get_waste_findings("w1-...", severity="high")

Example Response

[{
  "resource_id": "i-0abc123",
  "service": "EC2",
  "severity": "high",
  "estimated_monthly_savings": 45.20,
  "rule_name": "underutilized_instance",
  "recommendation": "Downsize from m5.xlarge to m5.large based on 14-day CPU average of 8%"
}]

Start KloudPilot Analysis

Start a full AI analysis. Scans 9 AWS services, enriches with 30 days of CloudWatch metrics, generates health score, recommendations, and savings estimates. Async.

Returns

analysis_id with polling hints.

Example

start_kloudpilot(cloud_account_id="a1-...")

Example Response

{ "analysis_id": "kp1-...", "status": "pending", "_next": { "poll_status": "get_kloudpilot_status('kp1-...')" } }

Get KloudPilot Results

Full results: overall health score (0-100), executive summary, top priorities ranked by impact, per-service breakdown with individual health scores, total savings from waste detection.

Returns

Complete analysis summary.

Example

get_kloudpilot_results("kp1-...")

Example Response

{
  "overall_health_score": 72,
  "executive_summary": "Your infrastructure is generally healthy with some optimization opportunities...",
  "top_priorities": ["Rightsize 3 underutilized EC2 instances ($45/mo savings)", "Enable S3 lifecycle policies ($12/mo savings)"],
  "services": { "EC2": { "health_score": 65, "resource_count": 8, "savings": 45.20 } },
  "total_savings": 156.30
}

Get Service Analysis

Drill into one AWS service from a completed analysis. Returns per-resource recommendations with waste detection savings merged in.

Returns

Service summary, list of resources with recommendations, waste_findings_count.

Example

get_service_analysis("kp1-...", "EC2")

Example Response

{
  "service": "EC2",
  "summary": { "health_score": 65, "potential_savings": 45.20 },
  "resources": [{
    "resource_id": "i-0abc123",
    "estimated_savings": 22.50,
    "priority": 1,
    "waste_detection": { "severity": "high", "rule_name": "underutilized_instance" }
  }],
  "waste_findings_count": 3
}

Dismiss Resource

Dismiss a resource finding. Excluded from the adjusted health score. Original score preserved for comparison. Idempotent.

Returns

New adjusted_score and dismissed_count.

Example

dismiss_resource("kp1-...", "i-0abc123", "EC2", "accepted_risk", "needs_attention", "Expected for batch processing")

Example Response

{ "success": true, "adjusted_score": 78, "dismissed_count": 1 }

Snooze Finding

Temporarily hide a waste finding from the active view. Can be un-snoozed later. Idempotent.

Returns

Confirmation.

Example

snooze_finding("i-0abc123", "underutilized_instance", "a1-...", note="Will fix next sprint")

Example Response

{ "ok": true }

Start Team KloudPilot

Run KloudPilot across all resources in a catalog. Aggregates results across multiple deployments and cloud accounts. Async.

Returns

analysis_id, resource_count, deployment_count with polling hints.

Example

start_team_kloudpilot(catalog_id="cat1-...")

Example Response

{ "analysis_id": "tkp1-...", "catalog_id": "cat1-...", "resource_count": 120, "deployment_count": 5, "_next": { "poll_status": "get_team_analysis_status('cat1-...', 'tkp1-...')" } }

Create Shell

Create a new shell. With cloud_account_id: AWS credentials pre-loaded. Without: sandbox mode. Up to 5 active shells. Connect via KloudHub web terminal.

Returns

Shell id, status, and optionally a shareable URL.

Example

create_shell(name="prod-debug", cloud_account_id="a1-...", generate_shareable_link=True)

Example Response

{
  "id": "sh1-...",
  "name": "prod-debug",
  "status": "running",
  "share_link": "https://kloudhub.io/share/shells/abc123token",
  "share_mode": "interactive",
  "_next": {
    "connect": "Open https://kloudhub.io/shells to connect via web terminal"
  }
}

List Shell Files

List files and directories inside a running shell without opening the terminal.

Returns

List of entries with name, size, is_dir, and path.

Example

list_shell_files("sh1-...", path="/home/clouduser/scripts")

Example Response

[{ "name": "deploy.sh", "size": 1024, "is_dir": false, "path": "/home/clouduser/scripts/deploy.sh" }]

Read Shell File

Read text content of a file on a shell. 50KB limit. Binary files rejected. Files over 50KB truncated.

Returns

File content as string, size in bytes, and whether truncated.

Example

read_shell_file("sh1-...", "/home/clouduser/deploy.sh")

Example Response

{ "path": "/home/clouduser/deploy.sh", "content": "#!/bin/bash\nterraform apply -auto-approve", "size_bytes": 42, "truncated": false }

Stop Shell

Stop one or more running shells. Supports batch.

Returns

Updated shell status.

Example

stop_shell("sh1-...")

Example Response

{ "status": "stopped" }