Skip to content

Connecting AI agents

Hyperkub runs an MCP server, so AI agents such as Claude can work with your clusters in conversation: “Which clusters are running?”, “What changed on production today?”, “Scale the workers pool to five nodes.”

The agent sees only the tools its key’s permissions allow, and every change it makes is recorded in the account’s activity under the key’s name.

https://mcp.hyperkub.com/mcp

The server speaks MCP’s Streamable HTTP transport and authenticates with a bearer token.

In the control plane, open Settings → Access Keys → Create Key and choose MCP as the type. See Managing access keys.

Give the agent as little as it needs:

  • To answer questions — read on clusters, node pools, nodes and activity.
  • To also scale pools, change their labels and taints, or restart nodes — add write on node pools or nodes.
  • To keep it to some clusters — limit the key to them, for instance to staging only.

When the key is created, the dialog shows it once, together with the commands below with your key filled in.

Terminal window
claude mcp add --transport http hyperkub https://mcp.hyperkub.com/mcp \
--header "Authorization: Bearer sk-hk-mcp01-…"

Then ask Claude about your clusters. claude mcp list shows whether it is connected.

To share the server with a project without sharing the key, put it in the project’s .mcp.json and read the key from the environment:

{
"mcpServers": {
"hyperkub": {
"type": "http",
"url": "https://mcp.hyperkub.com/mcp",
"headers": { "Authorization": "Bearer ${HYPERKUB_MCP_KEY}" }
}
}
}

Each person then sets HYPERKUB_MCP_KEY to their own key.

Any MCP client that connects to remote servers over Streamable HTTP and can send a custom header works. Most take a configuration like:

{
"mcpServers": {
"hyperkub": {
"type": "http",
"url": "https://mcp.hyperkub.com/mcp",
"headers": { "Authorization": "Bearer sk-hk-mcp01-…" }
}
}
}

Clients that support only local (stdio) servers, or only OAuth sign-in for remote ones, cannot connect directly.

The tools cover looking at clusters, pools, nodes and activity, resizing pools and restarting nodes — see the tool reference. Some things are deliberately left out:

  • Nothing deletes. No tool removes a cluster, pool, node or domain.
  • No kubeconfigs. An agent cannot issue or download cluster credentials: those are full administrator access to Kubernetes, which does not belong in an agent’s context.

Tools that change something — resizing a pool, restarting a node — are marked as such, and their descriptions ask the agent to confirm with you first. Clients like Claude Code also ask for your approval before running them.

Symptom Cause
The client cannot connect, 401 The key is wrong, expired or revoked, or it is a REST API key — the MCP server takes MCP keys only.
A tool you expect is missing The key lacks its permission. Keys cannot be edited: create a new key with it and revoke the old one.
A tool answers with an error The message is from Hyperkub and says why — a cluster outside the key’s limit answers 404, a pool that is busy resizing refuses another resize.
429 Too many requests for this key. The client should wait and retry.
The key stopped working It expired, was revoked, or the person who created it is no longer an owner or admin of the account.