npm package: @occam-scaly/mcp-server
Description: MCP server for Scaly - connect AI assistants to your cloud infrastructure
Author: Scaly
Latest version: 0.1.20

# @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`:

```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`:

```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:

```bash
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

```bash
# 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