scalr/mcp-server repository overview

⁠Scalr MCP Server - Quick Start Guide

Connect your AI assistant (Claude Desktop, Cursor, or any MCP-compatible client) to your Scalr infrastructure platform.

⁠What is this?

The Scalr MCP (Model Context Protocol) Server enables AI assistants to interact with your Scalr infrastructure through natural language. Ask questions, query resources, create workspaces, and manage your infrastructure—all through conversation.

Key Benefits:

• 🔐 Secure & Private: Runs locally on your machine, data never leaves your environment
• 🚀 Easy Setup: Just one Docker command to get started
• 🤖 AI-Powered: Works with Claude Desktop, VSCode Copilot, and other MCP clients
• 🛠️ 49 Tools: Full access to Scalr environments, workspaces, runs, modules, variables, IAM and analytics
• 🌐 HTTP Transport: Deploy as remote service

Transport Modes:

• stdio (default) — For local AI clients like Claude Desktop. Uses stdin/stdout communication. Token must be set via SCALR_API_TOKEN.
• HTTP — For network access: remote servers, multi-user scenarios, cloud-based AI agents. Supports per-request authentication via Authorization header.

⁠Prerequisites

• Docker installed on your machine
• Scalr account with API access
• Scalr API token (Personal Access Token or Service Account Token)
• MCP-compatible client (e.g., Claude Desktop⁠)

⁠Quick Start

⁠Step 1: Get Your API Token

Create a Scalr API token:

1. Go to your Scalr account settings
2. Navigate to Personal access tokens
3. Create a new token with appropriate permissions
4. Copy the token value

⁠Step 2: Configure Your AI Client

⁠Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "scalr": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull=always",
        "--env",
        "SCALR_API_TOKEN=your_api_token_here",
        "--env",
        "SCALR_API_URL=https://your-account.scalr.io",
        "scalr/mcp-server:latest"
      ]
    }
  }
}

Restart Claude Desktop to apply changes.

⁠Cursor IDE

1. Create or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "scalr": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--pull=always",
        "--env",
        "SCALR_API_TOKEN=your_api_token_here",
        "--env",
        "SCALR_API_URL=https://your-account.scalr.io",
        "scalr/mcp-server:latest"
      ]
    }
  }
}

1. Open Cursor: Settings → Cursor Settings → Tools & MCP
2. Enable the scalr toggle in Installed MCP Servers

⁠HTTP Transport

For remote integrations:

docker run -d \
  --pull always \
  --name scalr-mcp-server \
  -p 8000:8000 \
  -e SCALR_API_URL=https://your-account.scalr.io \
  -e MCP_TRANSPORT=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_LOG_FILE=/var/log/mcp/server.log \
  -v ~/mcp-logs:/var/log/mcp \
  scalr/mcp-server:latest

Authentication:

• Clients provide token via Authorization: Bearer <token> header (per-request)
• Or set SCALR_API_TOKEN environment variable as global fallback
• Per-request tokens take precedence over global token

Security:

• Configure CORS: -e MCP_CORS_ORIGINS='https://your-app.com'
• Restrict hosts: -e MCP_HTTP_ALLOWED_HOSTS='your-domain.com'

⁠Cursor IDE (HTTP)

If running the server in HTTP mode (MCP_TRANSPORT=http), use this configuration:

{
  "mcpServers": {
    "scalr-local": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer <your token>",
        "Content-Type": "application/json"
      }
    }
  }
}

Important for stdio clients: Replace:

• your_api_token_here with your actual Scalr API token
• your-account.scalr.io with your Scalr account URL (e.g., mycompany.scalr.io)

⁠Step 3: Start Using!

Open your AI client and try these example queries:

• "List all my Scalr environments"
• "Show me the workspaces in the production environment"
• "What runs are currently active?"
• "Create a new workspace named 'staging-app' in the dev environment"
• "Show me Terraform module usage across all workspaces"

⁠Configuration

⁠Environment Variables

The MCP server is configured through environment variables. All configuration options and their defaults:

* Token Requirements:

• stdio transport (Claude Desktop, Cursor): SCALR_API_TOKEN is required
• HTTP transport: SCALR_API_TOKEN is optional — clients can provide tokens via Authorization: Bearer <token> header per-request

⁠Available Tools

The MCP server provides 49 tools across 8 categories:

• Environments - List and get environment details
• Workspaces - List, get, and create workspaces with filtering
• Runs - List and monitor Terraform/OpenTofu runs
• Policy Groups - View policy groups and pull request policy check results
• Modules - Browse Terraform registry modules
• VCS Providers - List version control system providers
• Variables - List, get, and create workspace/environment variables
• IAM - Access policies, roles, teams, users, service accounts, and permissions
• Usage Analytics - Track module/provider/resource usage, Terraform versions, billing, and access tokens

Full tool list: All endpoints marked with x-mcp-tool: true in the Scalr OpenAPI Specification⁠ are available as MCP tools.

⁠Troubleshooting

⁠Claude Desktop doesn't show Scalr tools

1. Check configuration file syntax: Ensure your JSON is valid (use a JSON validator)
2. Restart Claude Desktop: Completely quit and reopen the application
3. Check Docker: Ensure Docker is running: docker ps
4. View logs: Check Claude Desktop logs for errors:
   • macOS: ~/Library/Logs/Claude/mcp-server-scalr.log
   • Windows: %APPDATA%\Claude\Logs\mcp-server-scalr.log
   • Linux: ~/.config/Claude/logs/mcp-server-scalr.log

⁠Authentication errors

1. Verify API token: Test your token with curl:

   curl -H "Authorization: Bearer YOUR_TOKEN" \
        https://your-account.scalr.io/api/iacp/v3/accounts
   

   Copy
2. Check token permissions: Ensure the token has appropriate read/write permissions

⁠Docker pull errors

If you see "pull access denied" or network errors:

# Manually pull the image to test connectivity
docker pull scalr/mcp-server:latest

# Check if image exists
docker images | grep scalr/mcp-server

⁠Tools not responding

1. Check API connectivity: Ensure you can reach your Scalr instance
2. Review rate limits: Check if you're hitting API rate limits
3. Increase timeout: Docker might need more time on slower connections

⁠HTTP Transport issues

1. 401 Unauthorized: Add Authorization: Bearer <token> header to requests
2. Connection refused: Ensure MCP_HTTP_HOST=0.0.0.0 for network access
3. Health check: Test with curl http://localhost:8000/health

⁠Example Queries

Here are some example questions you can ask Claude:

⁠Discovery & Exploration

• "What environments do I have in Scalr?"
• "Show me all workspaces in the production environment"
• "Which Terraform modules are most used?"
• "What versions of Terraform are running across my infrastructure?"

⁠Monitoring & Insights

• "Show me recent runs that failed"
• "What policy checks have failed recently?"
• "Show me usage statistics for AWS provider"

⁠Management

• "Create a workspace named 'new-app-staging' in the dev environment"
• "Show me details about workspace ws-abc123"
• "List all VCS providers configured in my account"

⁠Analytics

• "Which Terraform resources are most commonly used?"
• "Show me module usage by namespace"
• "What provider versions are in use?"
• "List all access tokens and their usage"
• "Extract all billing usage for today with breakdowns by workspace and environment"

⁠Security & Privacy

⁠Data Privacy

• All data stays local: MCP server runs in Docker on your machine
• Direct API calls: Your machine connects directly to your Scalr instance
• Token security: Tokens passed as environment variables, never stored

⁠Authentication

• stdio transport (Claude Desktop, Cursor): Requires SCALR_API_TOKEN environment variable
• HTTP transport: Supports per-request tokens via Authorization: Bearer <token> header OR global SCALR_API_TOKEN fallback

⁠Production Deployment

For HTTP transport in production, configure security settings:

• Restrict CORS origins: MCP_CORS_ORIGINS='https://your-app.com'
• Restrict allowed hosts: MCP_HTTP_ALLOWED_HOSTS='your-domain.com'
• Use per-request tokens for multi-user scenarios
• Rotate API tokens regularly

⁠Support & Resources

• Scalr Documentation: https://docs.scalr.io/docs/introduction⁠
• Scalr API Documentation: https://docs.scalr.io/reference/overview-1⁠
• Model Context Protocol: https://modelcontextprotocol.io/⁠
• Docker Hub: https://hub.docker.com/r/scalr/mcp-server⁠

⁠What's Next?

• Explore the full list of available tools
• Read the Scalr API documentation⁠ for advanced usage
• Integrate with your existing workflows
• Share feedback to help us improve

Version: 0.0.9