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.