AI-driven management (MCP)

HepCloud ships an MCP server. MCP (Model Context Protocol) is an open protocol that lets AI clients talk to external services. Once connected, you can write things like:

"List my servers." · "Create a 4 GB server." · "Show my database backups." · "Give me the connection details for the app database."

Your assistant turns these sentences into real HepCloud API calls. Resources are really created and really billed — this is not a simulation.

Get an API token first

MCP works with a token you create in the panel, and it is limited to that token's permissions. If you only want read access, issue a read-only token. See API tokens.

Two ways to connect

	Remote (recommended)	Local
Setup	None — address only (OAuth), or address + token	`hepmcp` binary on your machine
How it works	HTTPS to HepCloud's server	Client launches the binary itself
Suitable clients	Clients that speak OAuth or can send headers	Anyone avoiding an internet-facing endpoint

Both expose the same tools; only the location differs.

Connecting to the remote server

Address: https://mcp.hepcloud.net/mcp

Add this to your client's MCP configuration:

{
  "mcpServers": {
    "hepcloud": {
      "type": "http",
      "url": "https://mcp.hepcloud.net/mcp",
      "headers": { "Authorization": "Bearer <your API token>" }
    }
  }
}

We never store your token

The remote server keeps no customer tokens. It reads the token from each request's Authorization header and builds a connection scoped to that request. A single token stored server-side would mean anyone reaching the server could manage that account.

Setup per client

Every example below uses the same two pieces of information: the address (https://mcp.hepcloud.net/mcp) and — for clients that don't speak OAuth — the Authorization: Bearer <token> header. Menu names drift between client versions; these two don't.

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json in the project root:

{
  "mcpServers": {
    "hepcloud": {
      "url": "https://mcp.hepcloud.net/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Cline

In VS Code, open the Cline panel → MCP Servers → Remote Servers and enter a name plus the address; or edit cline_mcp_settings.json:

{
  "mcpServers": {
    "hepcloud": {
      "type": "streamableHttp",
      "url": "https://mcp.hepcloud.net/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

Roo Code

MCP → Edit Global MCP (or .roo/mcp.json in the project root):

{
  "mcpServers": {
    "hepcloud": {
      "type": "streamable-http",
      "url": "https://mcp.hepcloud.net/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

VS Code (Copilot agent mode)

From the command palette run MCP: Add Server → HTTP and paste the address — VS Code speaks OAuth, no token pasting needed. If you prefer a file, .vscode/mcp.json:

{
  "servers": {
    "hepcloud": { "type": "http", "url": "https://mcp.hepcloud.net/mcp" }
  }
}

Claude Code

claude mcp add --transport http hepcloud https://mcp.hepcloud.net/mcp

The first use opens an OAuth login; to connect with a token instead, add --header "Authorization: Bearer <token>".

claude.ai and Claude Desktop

Give the "add connector" interface just the address; the full flow is described in the OAuth section below.

Local (stdio) setup

Build from source:

go build -o hepmcp ./cmd/hepmcp

For Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "hepcloud": {
      "command": "/usr/local/bin/hepmcp",
      "env": { "HEP_TOKEN": "<your API token>" }
    }
  }
}

On Windows write the path as C:\\Program Files\\HepCloud\\hepmcp.exe — with double backslashes, since a single backslash is an escape character in JSON.

Tools

Read: server list and detail, server types, database list and detail, database types, backup list, point-in-time recovery window, database metrics, slow queries.

Write: create server, server power actions (on/off/reboot), create database.

Destructive: delete server, delete database, restore database to a point in time.

Destructive tools are OFF by default

Delete and restore tools are not shown to the assistant at all. A tool that isn't visible can't be called — safer than "we'll refuse if it's called", because a model may retry a refused tool but cannot try one that doesn't exist.

Turning them on is a deliberate choice:

"headers": {
  "Authorization": "Bearer <token>",
  "X-Hep-Allow-Destructive": "1"
}

In a local setup the equivalent is the HEP_MCP_ALLOW_DESTRUCTIVE=1 environment variable.

Before you enable them

With destructive tools enabled, a misunderstanding can become data loss. Leave them off for everyday use and delete resources from the panel.

Security boundaries

MCP is a thin shell over the API and carries no business rules of its own. Balance checks, project ownership, token scope and the audit trail all live in the control plane — so MCP cannot do anything you couldn't do in the panel.

Tokens are project-scoped. Another project's resource returns "not found". A read-only token cannot write.
Account endpoints are closed. Adding balance, the billing profile, 2FA and session management are not reachable with an API token; MCP cannot touch your account settings.
It cannot read your data. The SQL console and table browser exist only in the panel. MCP manages the database; it does not read what's inside. If you want your assistant to query your data, you provide the connection string yourself.
It never prints passwords. A database summary gives connection details but not the password, so it stays out of your chat history. The one exception is the root password when creating a server: it is returned once and lost if not passed on to you.
Every action is recorded in the audit trail, exactly as if it were done in the panel.

Connecting with OAuth (no token pasting)

The remote server speaks OAuth 2.1. If your client offers an "add connector" style interface, you only give it the address:

https://mcp.hepcloud.net/mcp

The rest happens on its own: the client registers itself, you land in the HepCloud panel, you choose which project and what permission you are granting, and you return to the app. You never paste a token anywhere.

Once granted, the connection appears in the panel's API tokens list under the application's name and can be revoked there with one click.

Access is time-limited, refresh rotates

Access is valid for 1 hour and renews itself in the background. The refresh key changes on every use; if an old one is presented again we treat it as theft and cut off ALL access for that application. You would then need to reconnect it.

If you prefer to supply a token by hand (or your client doesn't speak OAuth), the Authorization header method above keeps working exactly as before.

Troubleshooting

"Authorization header required" / 401 — no token was sent. Make sure your client supports a headers field and that the value starts with Bearer .

"Not found" — the token belongs to a different project. Switch to the right project in the panel and create a new token.

"token_readonly" — a write was attempted with a read-only token.

"Billing profile incomplete" / phone verification — creating a server requires a billing profile with a verified phone. Fill it in from the panel.

The delete tool isn't listed — that's expected; add the header above.