# Claude Desktop Setup Guide

Complete instructions for testing the CAST.AI MCP server with Claude Desktop.

---

## Step 1: Get Your CAST.AI API Key

1. **Visit CAST.AI Console**
   - Go to https://console.cast.ai
   - Log in to your account

2. **Navigate to API Keys**
   - Click **Settings** (gear icon in sidebar)
   - Click **API Keys**

3. **Create a New API Key**
   - Click **Create API Key** button
   - Give it a name: `Claude Desktop MCP` (or any name you prefer)
   - Choose **Read-only** access (recommended for safety)
     - This allows Claude to read cluster info but not make changes
   - Click **Create**

4. **Copy the API Key**
   - ⚠️ Copy the key immediately - you won't be able to see it again
   - Save it temporarily in a secure location

---

## Step 2: Configure Claude Desktop

### Find Your Configuration File

**macOS:**
```bash
# The config file is located at:
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```

### Edit the Configuration

1. **Open the config file in a text editor:**

   ```bash
   # macOS - using TextEdit
   open -a TextEdit ~/Library/Application\ Support/Claude/claude_desktop_config.json

   # Or using VS Code
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json

   # Or using nano
   nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
   ```

2. **Add the CAST.AI MCP server configuration:**

   If the file is **empty** or only has `{}`, replace it with:

   ```json
   {
     "mcpServers": {
       "castai": {
         "command": "uv",
         "args": [
           "--directory",
           "/Users/narunaskapocius/repos/github/castai-mcp-external",
           "run",
           "python",
           "main.py"
         ],
         "env": {
           "CASTAI_API_KEY": "YOUR_API_KEY_HERE"
         }
       }
     }
   }
   ```

   If the file **already has other MCP servers**, add the `castai` section:

   ```json
   {
     "mcpServers": {
       "existing-server": {
         "command": "...",
         "args": ["..."]
       },
       "castai": {
         "command": "uv",
         "args": [
           "--directory",
           "/Users/narunaskapocius/repos/github/castai-mcp-external",
           "run",
           "python",
           "main.py"
         ],
         "env": {
           "CASTAI_API_KEY": "YOUR_API_KEY_HERE"
         }
       }
     }
   }
   ```

3. **Replace placeholders:**
   - Replace `YOUR_API_KEY_HERE` with your actual CAST.AI API key
   - The path `/Users/narunaskapocius/repos/github/castai-mcp-external` should already be correct

4. **Save the file**

---

## Step 3: Restart Claude Desktop

1. **Quit Claude Desktop completely:**
   - macOS: Press `Cmd+Q` or right-click the dock icon → Quit
   - Windows: File → Exit

2. **Wait 2-3 seconds**

3. **Launch Claude Desktop again**

---

## Step 4: Verify the Server is Connected

1. **Look for the MCP indicator:**
   - In Claude Desktop, look for a small icon (usually 🔌 or hammer icon) near the text input
   - Click it to see connected MCP servers
   - You should see "CAST.AI" listed

2. **Check the logs if not connected:**
   ```bash
   # macOS - view MCP logs
   tail -f ~/Library/Logs/Claude/mcp*.log

   # Look for errors related to "castai"
   ```

---

## Step 5: Test with Natural Language

Now you can interact with your CAST.AI clusters using natural language!

### Example Queries

**List all clusters:**
```
Show me all my Kubernetes clusters
```

**Get cluster details:**
```
What are the details of my production cluster?
```

```
Show me information about cluster "my-gke-cluster"
```

**Check cluster policies:**
```
What policies are configured for my staging cluster?
```

**Get optimization score:**
```
What's the optimization score for my production cluster?
```

**View score history:**
```
Show me the cluster score history for my main cluster
```

**Complex queries:**
```
List all my clusters and tell me which one has the best optimization score
```

---

## Step 6: Troubleshooting

### Server Not Showing Up

**Check 1: Verify config file syntax**
```bash
# macOS - validate JSON syntax
python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

If you see an error, fix the JSON syntax (missing commas, quotes, brackets, etc.)

**Check 2: View MCP logs**
```bash
# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Look for lines containing "castai"
grep -i castai ~/Library/Logs/Claude/mcp*.log
```

**Check 3: Test server manually**
```bash
cd /Users/narunaskapocius/repos/github/castai-mcp-external
export CASTAI_API_KEY="your-key-here"
uv run python main.py
```

Expected output:
```
time="2026-02-22T..." level=info msg="Registering MCP tools" service=castai-mcp-external
time="2026-02-22T..." level=info msg="All MCP tools registered" service=castai-mcp-external
time="2026-02-22T..." level=info msg="Starting CAST.AI External MCP server" service=castai-mcp-external transport=stdio api_key_configured=true
```

Press `Ctrl+C` to stop.

### Authentication Errors

**Error: "Authentication failed (401)"**

Solutions:
1. Verify your API key is correct
2. Check if the key has expired in CAST.AI console
3. Ensure the key has proper permissions
4. Try creating a new API key

**Error: "CASTAI_API_KEY environment variable is required"**

Solutions:
1. Make sure you replaced `YOUR_API_KEY_HERE` in the config file
2. Verify the config file was saved
3. Restart Claude Desktop

### Cluster Not Found

**Error: "Cluster not found: cluster-name"**

Solutions:
1. List all clusters first: "Show me all my clusters"
2. Use the exact cluster name from the list
3. Or use the cluster UUID instead of the name
4. Verify your API key has access to that cluster

### Server Crashes or Timeout

**Check the MCP logs:**
```bash
# macOS
cat ~/Library/Logs/Claude/mcp-server-castai.log
```

Common issues:
- Network timeout (30 second limit)
- API rate limiting
- Invalid API endpoint

---

## Step 7: View Server Logs (Advanced)

To see real-time logs from the MCP server:

1. **Open a terminal**

2. **Tail the MCP logs:**
   ```bash
   # macOS
   tail -f ~/Library/Logs/Claude/mcp-server-castai.log
   ```

3. **Run queries in Claude Desktop**

4. **Watch the logs** for requests and responses

You'll see structured logs like:
```
time="2026-02-22T13:52:15.123Z" level=info msg="Starting CAST.AI External MCP server" service=castai-mcp-external transport=stdio api_key_configured=true
```

---

## Configuration Reference

### Full Example (macOS)

```json
{
  "mcpServers": {
    "castai": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/narunaskapocius/repos/github/castai-mcp-external",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "CASTAI_API_KEY": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz"
      }
    }
  }
}
```

### Using a Different API Endpoint (Optional)

If you're using a non-production CAST.AI environment:

```json
{
  "mcpServers": {
    "castai": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/narunaskapocius/repos/github/castai-mcp-external",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "CASTAI_API_KEY": "your-key-here",
        "CASTAI_API_URL": "https://api.dev-master.cast.ai"
      }
    }
  }
}
```

---

## Security Best Practices

1. **Use Read-Only Keys:** Create API keys with read-only access unless you need write permissions

2. **Never Share API Keys:** Don't commit your config file to version control

3. **Rotate Keys Regularly:** Generate new API keys periodically

4. **Use Organization-Scoped Keys:** API keys are automatically scoped to your organization

5. **Revoke Unused Keys:** Delete old API keys from the CAST.AI console

---

## Quick Reference Commands

```bash
# Edit Claude Desktop config (macOS)
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# View MCP logs (macOS)
tail -f ~/Library/Logs/Claude/mcp*.log

# Test server manually
cd /Users/narunaskapocius/repos/github/castai-mcp-external
export CASTAI_API_KEY="your-key"
uv run python main.py

# Validate JSON config
python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Find castai errors in logs
grep -i "castai\|error" ~/Library/Logs/Claude/mcp*.log
```

---

## Support

- **CAST.AI API Issues:** support@cast.ai
- **MCP Server Issues:** https://github.com/castai/castai-mcp-external/issues
- **Claude Desktop Issues:** https://claude.ai/docs

---

**Ready to test?** Follow Steps 1-5 above, then start asking Claude about your clusters! 🚀