Setting up MCP

Three steps: enable MCP on the server, create a key, point your assistant at it.

1. Enable MCP

Go to Settings → MCP and turn on Enable MCP. It is off by default, and nothing is reachable until you turn it on.

While you are there, look at Exposed tools. Every tool is enabled by default so MCP works immediately, but this list is a ceiling you control — anything switched off here cannot be called by any key, however broad that key's permissions are. There is a Read-only only preset if you would rather start conservatively.

2. Create an API key

Go to Settings → API Keys → Create API Key.

1. Give it a name that identifies the assistant, e.g. Claude Desktop — laptop.
2. Set permissions to the minimum the assistant needs. projects: read is enough to ask questions; projects: write is needed to start, stop or restart.
3. Turn on Allow MCP access.
4. Copy the key — it is shown only once.

An API key cannot be used by an assistant unless Allow MCP access is ticked. This includes keys created before MCP shipped, which stay disabled after upgrading. That is deliberate: a key issued for a cron job should not quietly become an AI assistant's credentials.

3. Configure your assistant

The MCP settings page shows a ready-to-paste snippet with your server URL and the correct connector version already filled in. The examples below show the shape.

Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "supascale": {
      "command": "npx",
      "args": ["-y", "@supascale/[email protected]"],
      "env": {
        "SUPASCALE_URL": "https://supascale.example.com",
        "SUPASCALE_API_KEY": "supascale_your_key_here"
      }
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add supascale \
  --env SUPASCALE_URL=https://supascale.example.com \
  --env SUPASCALE_API_KEY=supascale_your_key_here \
  -- npx -y @supascale/[email protected]

Cursor

Create .cursor/mcp.json in your project (or the global equivalent) using the same shape as the Claude Desktop example.

VS Code

Create .vscode/mcp.json using the same shape.

Why the version is pinned

The examples pin an exact version rather than a range like @1. That is deliberate: this connector holds your Supascale API key, and an exact pin means no upstream release can reach it without you choosing to move. Your Supascale install tells you which version it was tested with, and updates that value when you upgrade.

Checking it worked

Ask your assistant something harmless, like "list my Supascale projects".

Then open Settings → Logs. A successful connection writes an mcp.connected entry, and every tool call is logged with the time, the key used and the originating IP.

Requirements

Node.js 18 or newer on the machine running the assistant. Nothing to install on the server beyond Supascale itself.

The HTTP endpoint (advanced)

Some clients cannot launch a local subprocess and need to connect to a URL instead. For those, Settings → MCP → HTTP endpoint exposes /api/v1/mcp.

It is off by default and most installs should leave it that way — the local connector is simpler and does not require your server to be reachable. If you do enable it, see MCP security for the network restriction options, and read the note there about reverse proxies before relying on them.

Troubleshooting

"MCP is disabled on this server" — Settings → MCP → Enable MCP.

"This API key is not permitted to use MCP" — the key exists but does not have Allow MCP access. Edit it or create a new one.

"the server returned no tools" — the key has no permissions matching any enabled tool. Check the key's scopes against the tool list.

"Could not reach Supascale at ..." — wrong URL, server down, or this machine cannot route to it. A private address needs a VPN or tunnel.

Backup or project creation times out — these can run for minutes, and some clients give up after 60 seconds. Start the operation, then ask for its status separately rather than waiting on one call.