Skip to main content

Crusoe Cloud MCP Server

The Crusoe Cloud Model Context Protocol (MCP) Server enables AI models and agents to query and analyze your Crusoe AI infrastructure.

info

This feature is currently in Preview.

Prerequisites​

  • Node.js: v18 or higher.
  • Crusoe Credentials: An API key pair configured in ~/.crusoe/config (standard Crusoe CLI configuration).
  • MCP Client: An MCP-compliant client, such as Claude.

Installation​

If you have the Claude CLI installed, add the server directly:

claude mcp add crusoe-cloud -- npx -y @crusoeai/cloud-mcp

Option 2: Manual Configuration​

Add the server definition to your Claude Desktop configuration file.

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "crusoe-cloud": {
      "command": "npx",
      "args": ["-y", "@crusoeai/cloud-mcp"]
    }
  }
}

Restart Claude Desktop to apply changes.

Option 3: Other MCP Clients​

For other MCP-compliant agents (e.g., Cursor, Zed, or custom tools), use the following standard connection details:

  • Type: stdio
  • Command: npx
  • Args: -y, @crusoeai/cloud-mcp

Authentication​

The MCP server inherits authentication from your local Crusoe configuration file (~/.crusoe/config). It does not store credentials separately.

Default Setup​

If you already use the Crusoe CLI or Terraform provider and have a [default] profile in ~/.crusoe/config, no action is required.

Configuration via Environment Variables​

To use a specific profile from ~/.crusoe/config, or a specific project, add environment variables when you start a given server instance:

claude mcp add crusoe-cloud \
  -e CRUSOE_PROFILE=staging \
  -e CRUSOE_PROJECT_ID=48ca861f-d5ef-4faf-b141-0e4f786c587f \
  -- npx -y @crusoeai/cloud-mcp

Alternatively, pass them as environment variables in your configuration:

{
  "mcpServers": {
    "crusoe-cloud": {
      "command": "npx",
      "args": ["-y", "@crusoeai/cloud-mcp"],
      "env": {
        "CRUSOE_PROFILE": "staging"
      }
    }
  }
}

Usage Guidelines​

  • Security Note: Interaction with CLI: While this MCP server is strictly read-only, AI agents with shell or terminal capabilities may still modify your Crusoe infrastructure by invoking your installed crusoe CLI directly. The read-only constraint applies only to tools provided by this server, not to the agent's broader environment access.
  • Context Efficiency: Large lists are truncated (default 50 items) to prevent context window overflow. Use filters or specific get_ tools for granular data.
  • Rate Limiting: A client-side rate limit of 60 requests per minute is enforced to prevent accidental API quota exhaustion during AI retry loops. If this limit is hit, the assistant will be instructed to wait before retrying.

Available Tools​

The server exposes read-only tools organized by resource category. All write operations (create, update, delete) are disabled by design.

Core & Discovery​

  • get_user_identity: Get details of the currently authenticated user.
  • get_organization: Get organization details.
  • list_capacities: List available instance types (e.g., a100.8x) and availability.
  • get_current_project / list_available_projects: Inspect and list accessible projects.
  • use_project: Switch the active project for the current session.
  • get_resource_relationships: Generates a topology graph of resources (VMs, disks, VPCs) and how they connect. Useful for initial exploration.

Compute​

  • list_vms / get_vm: View virtual machines and their details.
  • list_instance_groups / get_instance_group: View managed instance groups.
  • list_instance_templates / get_instance_template: Inspect VM templates.
  • list_group_instances: List VMs belonging to a specific group.

Storage & Images​

  • list_disks / get_disk: View block storage volumes.
  • list_disk_snapshots / get_disk_snapshot: View storage snapshots.
  • list_images / get_image: View public VM images.
  • list_custom_images / get_custom_image: View user-created custom images.

Networking​

  • list_vpc_networks / get_vpc_network: View VPCs.
  • list_vpc_subnets / get_vpc_subnet: View subnets.
  • list_firewall_rules / get_firewall_rule: Inspect security rules.
  • list_load_balancers / get_load_balancer: View traffic distribution configurations.

Orchestration (Kubernetes)​

  • list_kubernetes_clusters / get_kubernetes_cluster: View CMK clusters.
  • list_kubernetes_node_pools / get_kubernetes_node_pool: Inspect node pools.
  • list_kubernetes_node_pool_instances: List specific nodes within a pool.
  • list_kubernetes_versions: Check supported K8s versions.

Operations & Billing​

  • list_audit_logs: Detailed logs of who did what and when.
  • list_org_quotas / list_project_quotas: Check resource limits vs. usage.
  • get_gpu_tracking: Monitor GPU utilization and reservation capacity.
  • get_usage_by_project: Retrieve usage data for billing analysis.

Troubleshooting​

"Crusoe credentials not found": Ensure ~/.crusoe/config exists and contains a valid [default] profile. You can verify this by running crusoe whoami in your terminal.

Rate Limit Errors: If you see "Rate limit exceeded," the assistant is making too many rapid queries. Ask the assistant to batch its requests or pause briefly.

Connection Errors: The server communicates with api.crusoecloud.com. Ensure your machine has outbound HTTPS access to this endpoint.

Disclaimer​

This is an experimental tool. Use with caution and at your own risk.

This MCP server enables AI assistants to query your Crusoe Cloud infrastructure through natural language. While the server performs read-only operations, you should be aware of the following:

Data Privacy​

  • API responses containing your infrastructure data will be sent to your chosen AI assistant (e.g., Claude, ChatGPT, or other services)
  • Your Crusoe API credentials remain local on your machine and are never sent to Crusoe or third-party AI services
  • Be mindful that VM names, network configurations, and other infrastructure details may contain sensitive business information

AI Decision-Making​

  • Always verify information before taking action. AI assistants may misinterpret infrastructure data or provide incorrect recommendations
  • This tool provides information only — it cannot and does not take any destructive actions
  • Never rely solely on AI-generated advice for critical infrastructure decisions

No Warranty​

This software is provided "AS IS" without warranty of any kind. Crusoe makes no guarantees regarding:

  • Stability or reliability of the tool
  • Accuracy of data filtering or response formatting
  • Compatibility with all AI assistants or future API changes