# Install the 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](/installing-the-cli)).
- **MCP Client**: An MCP-compliant client, such as [Claude](https://claude.ai/download).

## Installation

Choose the instructions for your MCP client below.

### Claude Code

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

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

### Claude Desktop

The simplest way to install in Claude Desktop is to download the bundled extension (`.mcpb`) and open it. Claude Desktop will prompt you to install it as an extension.

<a className="button button--primary button--lg" href="/downloads/cloud-mcp-latest.mcpb">Download Crusoe Cloud MCP (.mcpb)</a>

<br /><br />

Once downloaded, double-click the file (or open it from Claude Desktop's **Settings → Extensions**) to install.

<details>
<summary>Manual configuration (alternative)</summary>

You can also add the server definition directly to your Claude Desktop configuration file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "crusoe-cloud": {
      "command": "npx",
      "args": ["-y", "@crusoeai/cloud-mcp"]
    }
  }
}
```

Restart Claude Desktop to apply changes.

</details>

### Other MCP Clients

For other MCP-compliant clients (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:

```sh
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:

```json
{
  "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