Overview

Managing infrastructure through an API is powerful, but it requires knowing the right endpoints, structuring the right payloads, and writing the right scripts. For most requests, that means significant time spent before a single resource is touched.

The Scalr MCP Server removes that friction by connecting your AI assistant directly to the Scalr API. Instead of compiling API calls manually, you describe what you need in plain language, and the MCP server handles the translation. Requests that would have taken hours or days of scripting now take minutes.

Choose Your Setup

Method	Best for	Requirements
Remote MCP (OAuth)	Everyone: Easiest setup, no Docker, no token management	Account admin must enable the integration
Local stdio (Docker)	Personal use on your own machine; works in air-gapped or offline environments	Docker installed locally, personal API token
Local HTTP (Docker)	Team or org-wide deployment where multiple users share one server	Docker, a server or VM to host it, a reverse proxy for TLS in production

Jump to your role:

I'm a developer — I want to connect my AI client to Scalr
I'm a platform admin — I want to enable or deploy MCP for my team

For Developers

Connect your AI assistant (Claude, Cursor, VS Code) to Scalr and interact with your infrastructure in plain language. You can explore workspaces, investigate failing runs, query variables, review IAM policies, and more.

What MCP can and can't do: Most tools are read-only. Write operations are currently limited to creating workspaces and variables. Triggering runs, approving applies, and modifying existing resources are not yet supported via MCP.

Quickstart: Remote MCP (Recommended)

The fastest way to connect: no Docker, no token management. Your AI client authenticates using your own Scalr identity, so MCP inherits your existing permissions. It cannot access anything you cannot.

Prerequisite: Your account administrator must enable the integration first. If you get a connection error, ask them to go to Account Settings → Integrations → AI Assistant and toggle on Enable Scalr MCP.

Point your MCP client at https://your-account.scalr.io/mcp (replace your-account with your Scalr account name). When you connect for the first time, your client opens a browser window and redirects you to Scalr to approve access. After you approve, the connection is maintained automatically.

Claude

In Claude, go to Settings → Connectors and click Add custom connector. Enter https://your-account.scalr.io/mcp and click Connect. Complete the Scalr login and consent flow in the browser.

If you are using Claude Code, run in your terminal:

claude mcp add --transport http scalr https://your-account.scalr.io/mcp

Then start a Claude session and run:

/mcp

Select:
scalr → Authenticate

Cursor

In Cursor, go to Settings → Tools & MCP, click New MCP Server, and add the following to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "scalr-remote": {
      "url": "https://your-account.scalr.io/mcp",
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }
}

Save the file, go back to settings, and click Connect. You will be redirected to Scalr to authenticate.

Alternative: Local stdio (Docker)

Use this if the Remote MCP is not enabled in your account, or if you need to work in an air-gapped environment.

Prerequisites: Docker installed and running on your machine, and a Scalr API token (Personal Access Token or Service Account Token). Learn how to generate a token here.

Open Claude Settings
2. Navigate to Developer
3. Click Add MCP Server
4. Add the following to the config file.

{
  "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"
      ]
    }
  }
}

Replace your_api_token_here with your Scalr API token and your-account.scalr.io with your instance URL. Ensure Docker is running, then close and reopen Claude Desktop.

Example Prompts for Developers

Start with a simple question like "List all of my Scalr environments" to confirm the connection, then try these:

Investigating a failed run (the AI chains these tools automatically)

"Show me the most recent failed run in the production environment and explain what went wrong."
"Get the plan log for run run-abc123 and summarize the proposed changes."
"Find all runs that failed in the last 24 hours and group them by workspace."

Exploring your infrastructure

"Show me all workspaces in the production environment."
"Which workspaces have detected drift in the staging environment?"
"What versions of Terraform are running across my infrastructure?"
"Show me all variables set at the environment scope in production."

Creating resources

"Create a workspace named 'new-app-staging' in the dev environment."
"Add a Terraform variable named 'instance_type' with value 't3.medium' to workspace ws-abc123."

For Platform Administrators

Platform admins control whether MCP is available to their organization, how it is deployed, and what security boundaries are in place.

Enable the Remote MCP for Your Organization

The Remote MCP is the recommended option for teams. Each user authenticates with their own Scalr identity, so the AI assistant inherits that user's existing permissions, and it cannot access anything the user cannot. No shared credentials are required, and access is revoked automatically when a user's Scalr account is removed.

Required permission: integrations:manage at account scope.

To enable:

Go to Account Settings → Integrations → AI Assistant
Toggle on Enable Scalr MCP

Once enabled, users can connect their AI clients directly to https://your-account.scalr.io/mcp using OAuth — no Docker or token distribution required on your end.

To disable the integration account-wide or revoke an individual user's access, remove their Scalr account access. The OAuth session will no longer be valid.

Deploy an HTTP Server for Your Team

Use this option when users need to connect AI agents that cannot use OAuth (e.g., Amazon Q, GitHub Copilot, headless CI agents), or when you want to manage the connection centrally.

Single-user vs. multi-user token strategy

Scenario	Recommended approach
One developer, personal machine	Set `SCALR_API_TOKEN` globally, a simpler setup
Multiple users sharing one server	Do not set a global token. Require each user to provide their own `Authorization: Bearer <token>` header. This ensures each session is scoped to the user's own permissions.
Automated/CI workloads	Use a Service Account token with the minimum required permissions

Starting the server

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

Omit -e SCALR_API_TOKEN=... for multi-user deployments. Users will provide their own tokens via the Authorization: Bearer header in their client configuration.

Hardening for production

Setting	Default	Recommendation
`MCP_CORS_ORIGINS`	`*` (all origins)	Set to your client domain(s), e.g. `https://cursor.your-company.com`
`MCP_HTTP_ALLOWED_HOSTS`	`localhost,127.0.0.1,::1`	Set to your actual hostname — must change for any external access
TLS	Not included	Deploy behind nginx or Caddy to terminate HTTPS
Image version	`:latest`	Pin to a specific version (e.g. `scalr/mcp-server:0.0.10`) for stability

Configuring user clients for the HTTP server

Share this snippet with your team. They replace <your token> with their own Scalr API token.

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "scalr": {
      "url": "https://mcp.your-company.com/mcp",
      "headers": {
        "Authorization": "Bearer <your token>",
        "Content-Type": "application/json"
      }
    }
  }
}

Example Prompts for Platform Administrators

Access and security audits

"Review token usage in my account. Show tokens that don't have owners, have never been rotated, and don't have a description. Separate it into three outputs."
"Pull all users in my Scalr account that have an admin access policy."
"How many tokens have not been rotated in the last 30 days?"
"List all service accounts without an owner."
"Suggest ways to tighten my Scalr account security."
"List all users who are allowed to bypass SSO."

Usage and billing

"Extract all billing usage for this month with breakdowns by workspace and environment."
"Which Terraform provider versions are in use across the account?"
"Show me module usage by namespace."
"What versions of Terraform are running across my infrastructure?"

Drift and compliance

"Which workspaces in the production environment have detected drift?"
"What policy checks have failed recently?"
"Show me pull request policy check results for the last week."

Available MCP Tools

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

Write operations are limited. Creating workspaces and variables are the only write operations currently supported. Triggering runs, approving applies, and modifying existing resources are not yet available.

Category	Function	Description
Environments	`list_environments`	List all environments
	`get_environment`	Get details of a specific environment
Workspaces	`list_workspaces`	List all workspaces (with filtering and pagination)
	`get_workspace`	Get details of a specific workspace
	`create_workspace`	Create a new workspace
Runs	`list_runs`	List Terraform/OpenTofu runs
	`get_run`	Get details of a specific run
	`get_plan_log`	Get the plan console output for a run
	`get_apply_log`	Get the apply console output for a run
Policy Groups	`list_policy_groups`	List policy groups
	`get_policy_group`	Get details of a specific policy group
	`list_pull_request_policy_check_results`	List policy check results for pull requests
Modules	`list_modules`	List Terraform modules in the registry
	`get_module`	Get details of a specific module
VCS Providers	`list_vcs_providers`	List VCS (Version Control System) providers
	`get_vcs_provider`	Get details of a specific VCS provider
Variables	`list_variables`	List variables
	`get_variable`	Get detailed info about a specific variable
	`create_variable`	Create a variable in Scalr
Drift Reports	`list_drifted_workspaces_for_environment`	List workspaces with detected drift in an environment
Token Usage	`list_access_token_usage`	View access token usage statistics
Module Usage	`list_module_usage_namespaces`	List unique module namespaces
	`list_terraform_module_sources`	List unique Terraform module sources
	`list_terraform_module_usages`	List module usage across workspaces
	`list_terraform_module_usage`	Get detailed usage for a specific module
	`list_terraform_module_versions_usage`	List module versions in use
Provider Usage	`list_terraform_provider_sources`	List unique Terraform provider sources
	`list_terraform_provider_usages`	List provider usage across workspaces
	`list_terraform_provider_usage`	Get detailed usage for a specific provider
	`list_terraform_provider_versions_usage`	List provider versions in use
Resource Usage	`list_terraform_resource_providers`	List unique resource provider types
	`list_terraform_resource_usages`	List Terraform resource usage
	`list_terraform_resource_instances_usage`	List resource instances with details
Version Usage	`list_terraform_versions_usage_versions`	List Terraform/OpenTofu versions in use
Billing Reports	`list_billing_usage`	Returns information from the billing report
IAM	`get_access_policy`	Get details of a specific IAM access policy
	`get_account`	Get information about the current Scalr account
	`get_permission`	Get details of a specific IAM permission
	`get_role`	Get details of a specific IAM role and its permissions
	`get_service_account`	Get details of a specific service account
	`get_team`	Get details of a specific team
	`get_user`	Get details of a specific user
	`get_workload_identity_provider`	Get details of a specific workload identity provider
	`list_access_policies`	List all IAM access policies
	`list_permissions`	List all available IAM permissions
	`list_roles`	List all IAM roles
	`list_security_rules`	List account-level security rules and settings
	`list_service_accounts`	List all service accounts
	`list_sso_bypass_users`	List users allowed to bypass SSO
	`list_teams`	List all teams
	`list_users`	List all users
	`list_workload_identity_providers`	List all configured workload identity providers

Troubleshooting

Remote MCP: connection fails immediately

Confirm your account administrator has enabled the integration under Account Settings → Integrations → AI Assistant.
Verify the URL includes your account name: https://your-account.scalr.io/mcp — not https://scalr.io/mcp.

Claude Desktop doesn't show Scalr tools

Check your JSON config syntax (use a JSON validator).
Completely quit and reopen Claude Desktop.
Confirm Docker is running: docker ps.
Check logs:
- 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

Test your token directly:

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

Docker pull errors

docker pull scalr/mcp-server:latest
docker images | grep scalr/mcp-server

HTTP server: 401 Unauthorized

Add Authorization: Bearer <token> to your client's request headers.
Confirm SCALR_API_TOKEN is set if you are relying on the global fallback.

HTTP server: connection refused

Set MCP_HTTP_HOST=0.0.0.0 — the default 127.0.0.1 only accepts local connections.
Test with: curl http://localhost:8000/health.

HTTP server: CORS errors

Add your client's origin to MCP_CORS_ORIGINS, e.g. -e MCP_CORS_ORIGINS='https://your-app.com'.

Support & Resources

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