SCALE API Helper + MCP

A secure, LLM-ready bridge between your local AI environment and the SCALE Computing HyperCore REST API. Exposes VM management operations as authenticated FastAPI routes and MCP tools — usable from OpenWebUI, Claude Desktop, or cURL.

Built to go beyond API exploration: this is a functional operator tool for taking real actions against a SCALE HyperCore cluster.

Tested against SCALE HyperCore v9.4.30.217736 & v9.6.19.223352

Features

• FastAPI proxy server with Bearer Auth securing all routes

• MCP tool integration for OpenWebUI and Claude Desktop

• Session-based auth against SCALE HyperCore (stored locally in .p file)

• VM lifecycle management: snapshot, clone, export, state changes

• Swagger UI at /docs with full OpenAPI schema

• RAG-compatible schema querying for LLM-assisted API exploration

Related MCP server: proxmox-mcp

File Overview

Requirements

• Python 3.10+

• MCP runtime via uvx mcpo

• Dependencies: fastapi, httpx, pydantic, uvicorn

• any OpenAI API Compat. Server — tested with nvidia/NVIDIA-Nemotron-3-Nano-4B-FP8 on vLLM (0.18.1)

Setup

1. Clone & Install

git clone https://github.com/Nels2/SCALE-API-Helper-MCP
cd SCALE-API-Helper-MCP
uv pip install -r requirements.txt

2. Configure

Edit config_alt.py:

MCP_BEARER_TOKEN = "your-secret-token"
SCALE_HOST = "your-cluster-ip"

3. Run

uvx mcpo --port 5075 -- uvicorn 03_mcpserver_agent+auth:app --host 0.0.0.0 --port 5075

Optionally, add --reload if you plan to make changes and dont wan't to kill the server.

Swagger UI: http://localhost:5075/docs

MCP Usage

OpenWebUI

uvx mcpo --port 5075 -- uv run fastapi_server.py

Add connection in OpenWebUI:

URL:  http://<your-ip>:5075/openapi.json
Auth: Bearer <your-token>

Note: After adding new tools to the MCP server, restart the server process and reconnect in OpenWebUI — tool lists are cached at connection time.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "scale-agent": {
      "url": "http://<your-ip>:5075",
      "headers": {
        "Authorization": "Bearer <your-token>"
      }
    }
  }
}

Available Tools

Session Management

Read Operations

VM Operations

Raw Access

Architecture

OpenWebUI / Claude Desktop
        │
        ▼
  fastapi_server.py  ←── Bearer Auth
        │
        ▼
  scale_tools.py  ←── Session (.p file)
        │
        ▼
  SCALE HyperCore REST API

Notes

• This is a personal developer tool but it IS technically production-hardened since it is secured by Bearer Auth.

• The SCALE API uses session cookies, not per-request tokens; the .p file persists this between calls, it is only valid based on the SCALE Permissions, but the script sets a hard time of 12 hours to auto refresh token.

• run_api gives you a raw escape hatch for any endpoint not yet wrapped as a named tool... but your model has to be smart enough to handle embedded JSON within JSON.

License

MIT. Use and adapt freely.