MCP server
kubehz runs a remote Model Context Protocol (MCP) server. An AI app such as Claude or ChatGPT can use it to work with your clusters and Spaces:
https://mcp.kubehz.cloud/mcpEach tool call goes through the kubehz API, with the same checks as the dashboard. The app can never do more than the person or the agent key that it acts for.
There are two ways to connect:
- As yourself. The app signs you in, and you allow it once. Then the app acts as you, within the permissions that you allowed.
- With an agent key. No person signs in. The tools act within the role, the scope and the spend cap of the key.
Switch on AI apps
AI apps are off by default. While they are off, no app can act for a member of the tenant. Agent keys do not depend on this setting.
You need the role Owner or Admin.
- In the dashboard, open Settings → AI apps.
- Switch on Allow AI apps (MCP).
- Confirm with your second factor.
To switch AI apps off needs no second factor. All connected apps then stop at once, for every member. The apps stay in the lists. When an owner or an admin switches AI apps on again, the apps work again.
Connect an app as yourself
kubehz accepts these apps:
- Claude on claude.ai or claude.com.
- ChatGPT on chatgpt.com.
- An app on your own computer that receives the sign-in on a loopback address, for example Claude Code, Claude Desktop or an IDE.
kubehz refuses other hosted apps.
Claude
- In Claude, add a custom connector.
- As the URL, paste
https://mcp.kubehz.cloud/mcp. - Connect the connector.
- Sign in to kubehz.
ChatGPT
- In ChatGPT, create a connector.
- As the URL, paste
https://mcp.kubehz.cloud/mcp. - As the authentication, select OAuth.
- Connect the connector.
- Sign in to kubehz.
Claude Code and other local apps
claude mcp add --transport http kubehz https://mcp.kubehz.cloud/mcpAnother local app needs only the URL, if it supports remote MCP servers with OAuth.
The first time, the app registers itself at id.kubehz.cloud and opens the kubehz sign-in page. After you sign in, kubehz shows the screen Allow this app?.
The screen “Allow this app?”
The screen shows:
- the name of the app. The app chose this name itself.
- what the app can do as you.
- the address that you return to.
Do not trust the name. Check the return address instead. Expect:
- claude.ai or claude.com for Claude.
- chatgpt.com for ChatGPT.
127.0.0.1,localhostor[::1], with a port number, for an app on your computer.
Click Deny if you did not start the app just now, or if the return address does not belong to the app that you started. The app then gets no access. Click Allow only if both are correct.
kubehz asks once per app. A later sign-in skips the screen. If the app asks for a new permission later, the screen asks only for the new permission.
Your role is the limit. The app can never do more than you can.
By default, the app acts in the tenant that you joined first. The app can choose another of your tenants. It works there only if that tenant has AI apps switched on. The tool whoami shows the tenant.
Permissions
An app gets nothing beyond whoami until it asks for a permission. The screen shows the permissions that the app asks for. The dashboard shows each one with a short name.
| On the screen | In the dashboard | Tools |
|---|---|---|
| See who you are. | Identity only | whoami |
| See your spaces and clusters and get their kubeconfig files. The files hold no secrets. | See spaces and clusters | list_spaces, get_space, space_kubeconfig, list_clusters, get_cluster, cluster_kubeconfig |
| Create and delete spaces and set their lease (when they expire). | Create and delete spaces | create_space, delete_space, set_space_lease |
| Set the lease of your clusters (when they expire). | Set cluster leases | set_cluster_lease |
When an app calls a tool without the permission for it, kubehz refuses the call and names the permission. The app can then sign you in again and ask for it.
Tools
| Tool | Permission | What it does |
|---|---|---|
whoami | None | Shows the caller: the agent key (role, scope, expiry, spend this month, reach) or the person (tenant and role) |
list_spaces | See spaces and clusters | Lists the Spaces that the caller reaches, with status, limits and lease |
get_space | See spaces and clusters | Shows one Space: status, endpoint, nodes, limits and lease |
space_kubeconfig | See spaces and clusters | Gives the kubeconfig of a Space, for an agent key (the default) or for a person |
list_clusters | See spaces and clusters | Lists the clusters that the caller reaches, hosted and self-hosted |
get_cluster | See spaces and clusters | Shows one cluster: status, version, workers and health |
cluster_kubeconfig | See spaces and clusters | Gives the agent kubeconfig of a hosted cluster |
create_space | Create and delete spaces | Creates a Space. It is ready in seconds and billed per hour |
delete_space | Create and delete spaces | Deletes a Space and everything in it. You cannot undo this. As yourself, the call fails (see below) |
set_space_lease | Create and delete spaces | Sets when kubehz deletes a Space: 1 to 720 hours from now. As yourself, only a later end works |
set_cluster_lease | Set cluster leases | Sets when kubehz deletes a hosted cluster: 1 to 720 hours from now. As yourself, only a later end works |
As yourself, an app cannot delete a Space or bring the end of a lease closer. A first lease on a Space or a cluster without one also brings the end closer. Each of these needs your second factor, and the app cannot give it. Delete the Space, or shorten the lease of a Space, in the dashboard. A Space that the app creates without a lease stays until you delete it.
An agent key needs no second factor. With the role Editor or Admin, it can delete a Space and set any lease end between 1 and 720 hours from now.
No kubeconfig holds a secret. The agent kubeconfig runs lo kubehz token with the key from the environment. The kubeconfig for a person signs the person in through the browser.
An agent key does not use these permissions. Its role decides. A key with the role Viewer can use only whoami and the tools that read.
Connect an agent with a key
An agent without a person uses an agent key. The agent gets a token with the key and sends it as Authorization: Bearer. No screen asks for consent, and the AI apps setting does not apply. What the agent creates gets a lease.
TOKEN=$(lo kubehz token --format token)
curl -s https://mcp.kubehz.cloud/mcp \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'A token expires. When the server answers 401, get a new token with the key.
Yourself or an agent key
| As yourself | With an agent key | |
|---|---|---|
| Who acts | You, through the app | A machine identity |
| Limit | Your role and the permissions that you allowed | The role, the scope and the spend cap of the key |
| AI apps setting | Must be on | Does not apply |
| What it creates | Has a lease only if the app sets one | Always has a lease |
| Delete a Space or bring a lease end closer | Not through the app: it needs your second factor | With the role Editor or Admin |
| Where you see it | Settings → AI apps | Access → Agent keys |
| How it ends | You revoke it, or kubehz deletes the unused app | You revoke the key, or it expires |
See and revoke connected apps
In Settings → AI apps, every member sees Your connected apps. An Owner or Admin also sees All connected apps in this tenant. An app shows in the list after its first tool call. Each row shows the name of the app, its Permissions, when the person allowed it (Allowed), and when the app was first and last used (First used, Last used).
To revoke an app:
- Open Settings → AI apps.
- On the row of the app, click Revoke.
- In the dialog, click Revoke.
- Your own app stops at once, in every tenant. To use it again, sign in to kubehz from the app and allow it again.
- An Owner or Admin can revoke an app for a member. The app stops for this member in this tenant at once. At the next sign-in, kubehz asks the member to allow the app again.
After a revoke, only a new sign-in works. A token from an earlier sign-in never works again.
kubehz deletes registered apps that nobody uses:
- an app that nobody allowed and used in the 7 days after it registered.
- an app that nobody used for 90 days.
To use a deleted app again, connect it again.
Local MCP with lo
lo mcp is a different server. It runs on your own computer and offers the lo commands of a lok8s project as tools to your editor or agent. By default it offers only the commands that read. It never offers a command whose output is a credential. Its lo kubehz space and lo kubehz cluster tools call the kubehz API with an agent key. Commands outside lo kubehz need no kubehz account. See the lok8s MCP guide and the lo mcp reference.