@occam-scaly/mcp-server

Model Context Protocol (MCP) server for Scaly. Connect your AI assistant (Claude, Cursor, etc.) to manage your Scaly infrastructure.

Quick Start

Note: If @occam-scaly/mcp-server is not published to npm yet, run it from a local checkout of the Scaly repo (see “Development” below) and point your MCP client at packages/mcp-server/bin/scaly-mcp.js.

1. Get your keys

Go to Scaly Dashboard → Settings → Integrations → AI Assistants and generate:

• Scaly API key (SCALY_API_KEY)
• Stage (SCALY_STAGE=prod|dev|qa) if you’re not on prod (note: staging is an alias for qa)

Advanced overrides (usually not needed for Scaly hosted environments):

• MCP access key (SCALY_APPSYNC_KEY) — the MCP server ships safe defaults for prod|dev|qa
• Session token (SCALY_OIDC_TOKEN) — manual override for DB/storage/logs tools (recommended: scaly auth login)

2. Configure your AI assistant

Claude Desktop - Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "scaly": {
      "command": "npx",
      "args": ["-y", "@occam-scaly/mcp-server"],
      "env": {
        "SCALY_API_KEY": "sk_live_your_key_here",
        "SCALY_STAGE": "prod"
      }
    }
  }
}

Claude Code - Add to your Claude Code MCP settings.

Cursor - Add a new MCP server and use the same command/args/env values.

Gemini - If your Gemini host supports MCP servers, configure the same Scaly MCP server definition (npx -y @occam-scaly/mcp-server + env vars). If it doesn’t, use an MCP-capable host (Claude Desktop, Cursor, Codex, etc.).

Codex (CLI + VS Code extension) - Add to ~/.codex/config.toml:

[mcp_servers.scaly]
command = "npx"
args = ["-y", "@occam-scaly/mcp-server"]

[mcp_servers.scaly.env]
SCALY_API_KEY = "sk_live_your_key_here"
SCALY_STAGE = "prod"

Note: Codex config is TOML. Do not paste the Claude JSON block into config.toml.

3. Enable advanced tools (DB/storage/logs) — no restart

Run:

npx -y @occam-scaly/scaly-cli auth login

This stores a short-lived Scaly session token in ~/.config/scaly/auth.json. The MCP server reads it on-demand, so you can refresh without restarting VS Code/Codex.

4. Restart your AI assistant

The Scaly tools will now be available.

Available Tools

All tools return JSON-only responses (wrapped in MCP content[].text).

Core inventory

• scaly_auth_status - Session token status for advanced tools
• scaly_status - Overview of stacks/apps + running deployments
• scaly_list_apps / scaly_get_app
• scaly_list_stacks / scaly_get_stack (alias: scaly_list_compute)
• scaly_list_addons / scaly_get_addon
• scaly_list_jobs / scaly_run_job

Deployments & operations

• scaly_list_deployments / scaly_get_deployment (alias: scaly_get_deployment_status)
• scaly_deploy_app (currently implemented as stack service restart)
• scaly_restart_stack_services
• scaly_retry_deployment
• scaly_get_operation / scaly_wait_operation / scaly_get_operation_events

Configuration

• scaly_set_env (alias: scaly_set_env_var) – blocks secret-like keys, never echoes values
• scaly_get_env_vars – returns names only

Project config

• scaly_plan – computes a plan from .scaly/config.yaml and returns plan_hash
• scaly_apply – applies a plan (requires plan_hash and auto_approve: true)
• scaly_pull – writes .scaly/config.yaml by reverse-engineering live state

Write tools (imperative)

• scaly_create_stack / scaly_update_stack / scaly_delete_stack (preview-first; delete requires confirm)
• scaly_create_database / scaly_create_storage
• scaly_create_app
• scaly_link_addon
• scaly_configure_auth

User Groups

• scaly_list_user_groups
• scaly_create_user_group
• scaly_delete_user_group

Notes:

• Phase 4 intentionally omits add-on updates/resizes, add-on deletion, and unlink operations.

Logs & diagnostics

• scaly_get_logs (unified logs)
• scaly_diagnose_app

Database & storage (requires session token)

• scaly_db_query / scaly_db_execute
• scaly_db_migration_plan / scaly_db_migrate / scaly_db_schema_dump
• scaly_s3_list_objects / scaly_s3_download_object
• scaly_s3_upload_object / scaly_s3_delete_object (currently NOT_SUPPORTED)

Resources

• scaly://capabilities (YAML)
• scaly://resources-schema (JSON Schema)
• scaly://guides/platform (Markdown)
• scaly://guides/golden-paths (Markdown)
• Templates: scaly://guides/frameworks/{name}, scaly://guides/patterns/{name}, scaly://apps/{id}, scaly://stacks/{id}

Example Usage

You: "What apps do I have running?"

Claude: [Calling scaly_list_apps]

        {"success":true,"data":{"apps":[...],"count":3},"meta":{...}}

You: "Deploy ml-api"

Claude: [Calling scaly_deploy_app]

        {"success":true,"data":{"operation_id":"dep_abc123",...},"meta":{...}}

Environment Variables

| Variable | Required | Description | | ----------------------- | -------- | --------------------------------------------------------------------------- | | SCALY_API_KEY | Yes | Your Scaly API key | | SCALY_APPSYNC_KEY | No | MCP access key (defaults for prod/dev/qa) | | SCALY_OIDC_TOKEN | No | Session token override for advanced tools (recommended: scaly auth login) | | SCALY_AUTH_STORE_PATH | No | Override auth store path (default: ~/.config/scaly/auth.json) | | SCALY_MCP_AUDIT | No | Enable audit logging (true by default; set false to disable) | | SCALY_MCP_AUDIT_FILE | No | Write audit logs as JSONL to this file path (defaults to stderr) | | SCALY_STAGE | No | prod (default), dev, qa (staging alias) | | SCALY_API_URL | No | Override API URL |

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Type check
npm run typecheck

Security

• API keys are scoped to specific permissions
• Tool outputs are treated as durable transcripts; avoid returning secrets or credentials
• Never store API keys in version control
• Revoke keys immediately if compromised

Support

• Documentation: https://docs.scalyapps.io/mcp
• Issues: https://github.com/scaly-cloud/mcp-server/issues