@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
• scaly_invite_user_group_users
• scaly_add_users_to_group / scaly_remove_users_from_group

App User Groups users are the people who sign in to private apps. They are separate from Scaly control-plane/workspace users; invite app users before adding them to restricted groups.

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_storage_list_objects / scaly_storage_download_object
• scaly_storage_upload_object / scaly_storage_delete_object

Resources

• scaly://capabilities (YAML)
• scaly://guides/start (Markdown)
• scaly://resources-schema (JSON Schema)
• scaly://guides/platform (Markdown)
• scaly://guides/golden-paths (Markdown)
• scaly://guides/build-plan (Markdown)
• scaly://guides/data/database (Markdown)
• scaly://guides/data/storage (Markdown)
• Templates: scaly://guides/frameworks/{name}, scaly://guides/patterns/{name}, scaly://apps/{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 |

Streamable HTTP Transport

Stdio remains the default transport for local LLM clients. For Phase E compatibility work, the server can also run a Streamable HTTP endpoint:

SCALY_MCP_TRANSPORT=http \
SCALY_API_KEY=sk_live_... \
npm run dev

HTTP mode binds to 127.0.0.1:8765 by default and every /mcp request must include Authorization: Bearer $SCALY_API_KEY. This keeps E.1 safe-by-default: do not expose the HTTP endpoint publicly without an auth layer. Override the bind address with SCALY_MCP_HTTP_HOST and SCALY_MCP_HTTP_PORT only for controlled dev/probe environments. Any non-localhost bind requires SCALY_MCP_ALLOWED_HOSTS (comma-separated Host header allowlist); the server refuses to start without it so DNS-rebinding protection stays explicit. Set SCALY_MCP_PUBLIC_URL when the externally visible URL differs from the local listener, and SCALY_MCP_AUTHORIZATION_SERVERS to advertise one or more OAuth authorization-server metadata URLs during Phase E compatibility probes.

HTTP mode also serves RFC 9728 OAuth Protected Resource Metadata for /mcp at:

• /.well-known/oauth-protected-resource/mcp
• /.well-known/oauth-protected-resource

Unauthorized /mcp responses include the matching resource_metadata parameter in WWW-Authenticate. This is resource-server conformance only; the server does not issue OAuth tokens in this mode.

For Phase E compatibility probes only, a fake OAuth server can be enabled in non-prod stages:

SCALY_STAGE=dev \
SCALY_MCP_TRANSPORT=http \
SCALY_MCP_OAUTH_PROBE=unsafe-dev-only \
SCALY_API_KEY=sk_live_... \
npm run dev

Probe mode serves RFC 8414 metadata plus /oauth/probe/register, /oauth/probe/authorize, and /oauth/probe/token. It mints one process-local test bearer token and accepts that token at /mcp so real MCP clients can be walked through metadata discovery, registration, browser login, token exchange, and a tool call. The mode refuses to start in prod and is not product auth. Redirects default to localhost origins; add SCALY_MCP_OAUTH_PROBE_REDIRECT_ORIGINS only for controlled client probes. Redirect matching checks protocol + hostname and intentionally ignores the port so real clients can use random localhost callback ports.

Delete the fake /oauth/probe/* code path after the compatibility matrix is published. It is intentionally bundled only as a temporary E.2 probe harness; the product OAuth authorization server starts in E.3.

The same mode works through the published package:

SCALY_MCP_TRANSPORT=http \
SCALY_API_KEY=sk_live_... \
npx -y @occam-scaly/mcp-server

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