MCP: connecting Claude and other agents
How to give an AI agent (Claude Code or any MCP client) the tools to manage your project, and how to keep it on a leash.
What it is
MCP (Model Context Protocol) is the way an AI agent discovers and uses a service's tools. Gigakube has an MCP server with 51 tools cloud_*: one for each cloud operation, the same ones the panel's assistant uses and the same as the API methods. What the agent cannot do with the MCP, the panel cannot do either, and vice versa.
| Endpoint | https://gigakube.ch/api/mcp |
| Transport | HTTP (streamable HTTP): one JSON-RPC message per POST, JSON response, no session |
| Authentication | Authorization: Bearer gk_…, an API key |
| Protocol versions | 2025-06-18, 2025-03-26, 2024-11-05 |
The key decides the project and the role: the agent sees and touches only that project, and only as far as the role allows.
Which key to give an agent
The recommended choice for an AI agent:
- role Can edit (or Can view if it only needs to look);
- Requires my approval for every change switched on: the agent reads everything, but every change becomes a change request that a person in the project approves or rejects from the panel, with the plan of what will change (Plans and change requests);
- an expiry date, if it is a trial.
A key that requires approval cannot even open a server's console or read a cluster's kubeconfig: with those, it could change everything without asking anyone.
Create the key from API & agents → New API key and copy the secret (it is shown only once).
Claude Code
From the terminal:
claude mcp add --transport http gigakube https://gigakube.ch/api/mcp \
--header "Authorization: Bearer gk_…"
Or, for a repository, a .mcp.json file at its root that reads the key from an environment variable (so the secret does not end up in the repository):
{
"mcpServers": {
"gigakube": {
"type": "http",
"url": "https://gigakube.ch/api/mcp",
"headers": { "Authorization": "Bearer ${GIGAKUBE_API_KEY}" }
}
}
}
export GIGAKUBE_API_KEY=gk_…
claude
In Claude Code, /mcp shows whether the gigakube server is connected, and its tools. Then ask in your own words, for example:
- "List the servers in the Gigakube project with their state and addresses."
- "Create a server
api-1s-2-4 with Ubuntu, my key~/.ssh/id_ed25519.pub, ports 80 and 443 open. Show me the plan first." - "Which ports are open to the whole internet? Restrict 22 to my address 203.0.113.7."
- "Add an A record
apito the zoneexample.chpointing to the address ofapi-1." - "How much has this project cost this month?"
With a key that requires approval, the agent tells you the change is waiting for approval: you will find it in the panel, in Cloud → Requests (and a number next to the Cloud menu item), or in the email sent to the people who can decide.
Claude Desktop and Claude.ai (connectors)
Remote connectors in Claude Desktop and Claude.ai connect with an authorization from the browser (OAuth), not with a pasted key. This route is not active on the portal yet: today you can only get into the MCP with an API key, so with clients like Claude Code that let you set the Authorization header. When browser authorization is available, connected applications will appear in API & agents → Connected applications.
Other agents and clients
Any MCP client that speaks HTTP and lets you add the Authorization: Bearer … header works the same way. If a client tries to open an event stream with a GET, the server answers 405: this is allowed by the protocol, and clients handle it.
Trying it with curl
# who you are and what the server can do
curl -s https://gigakube.ch/api/mcp \
-H "Authorization: Bearer $GIGAKUBE_API_KEY" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'
# the list of tools
curl -s https://gigakube.ch/api/mcp \
-H "Authorization: Bearer $GIGAKUBE_API_KEY" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | jq -r '.result.tools[].name'
# one tool
curl -s https://gigakube.ch/api/mcp \
-H "Authorization: Bearer $GIGAKUBE_API_KEY" -H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"cloud_get_server_list","arguments":{}}}'
A tool's result is in result.content[0].text (the JSON as text) and in result.structuredContent. A refusal (wrong data, quota, role) is not a protocol error: it comes back as a result with "isError": true and a text such as invalid_request: … or forbidden: …, so the agent reads it and corrects itself.
How the tools behave
- Every tool declares whether it only reads (
readOnlyHint) or destroys (destructiveHint): the client knows when to ask you for confirmation before calling it. - Every tool that changes something accepts two extra fields:
dry_run: true: answers with the plan (what would be created, changed or destroyed, the quota afterwards, whether it can be undone) without changing anything;reason: why the agent is asking for the change, in one sentence. The person who has to approve it sees it.- With a key that requires approval, a tool that writes answers with a
change_requestand the message Nothing was changed yet; the agent follows it withcloud_get_change_request. - Long-running operations (creating a server, a cluster) wait up to about 25 seconds; if they have not finished, they come back with a job to follow with
cloud_get_job. - Deleting a server, a cluster or a node pool cannot be undone: the server's instructions tell the agent to ask you first.
- The kubeconfig is a credential with full rights: the instructions tell the agent not to print it in the chat.
The tools
In the list: R only reads, W writes, D destroys (no undo). The minimum role is in brackets.
Project, catalog, costs
cloud_get_statusR (viewer): cloud switched on, network, role, quota used.cloud_activateW (admin): switches on the cloud in the project.cloud_get_catalogR: sizes, images, public networks, Kubernetes versions, zones for replication.cloud_get_costsR: the project's usage and cost per resource, with a total per day (date_from,date_to).cloud_get_jobR: state of a long-running operation.
Servers
cloud_get_server_listR,cloud_get_serverR.cloud_create_serverW (operator):name,size,image,disk_gb,public_ip,public_ip_pool,ssh_key,open_ports,source,reverse_dns.cloud_server_actionW:start,stop,reboot.cloud_delete_serverD.cloud_set_reverse_dnsW: reverse DNS.cloud_get_consoleR (admin): a link to the console, to be opened within 60 seconds.cloud_get_volume_listR.
Firewall
cloud_get_firewallR,cloud_open_portW,cloud_update_portW,cloud_close_portW.
Addresses and networks
cloud_get_public_ip_listR,cloud_get_public_ip_pool_listR.cloud_get_network_listR,cloud_get_networkR,cloud_create_networkW,cloud_delete_networkD,cloud_attach_server_to_networkW,cloud_detach_server_from_networkW.
Kubernetes
cloud_get_kubernetes_cluster_listR,cloud_get_kubernetes_clusterR.cloud_create_kubernetes_clusterW,cloud_set_kubernetes_node_poolW.cloud_delete_kubernetes_node_poolD,cloud_delete_kubernetes_clusterD.cloud_get_kubernetes_kubeconfigR (admin).
Imports (where the zone offers them)
cloud_import_serverW,cloud_get_import_listR,cloud_get_importR,cloud_start_importW,cloud_connect_importW,cloud_cancel_importD.
Replication to another zone (where the zone offers it)
cloud_get_replication_listR: the copy policies and each server's latest copy.cloud_set_replicationW: creates or changes a policy (name,target_zonefrom the catalog'sreplica_zones,servers,interval_minutes60–10080,keep1–90,suspended).cloud_delete_replicationW,cloud_run_replicationW.cloud_get_restore_point_listR: the restore points.cloud_restore_replicaW: brings a restore point back as a new server, stopped and disconnected, to be followed like an import.
Protection
cloud_get_attack_listR: the attacks on your addresses.
DNS
cloud_get_dns_zonesR,cloud_get_dns_recordsR,cloud_set_dns_recordW,cloud_delete_dns_recordW.
Change requests
cloud_get_change_request_listR,cloud_get_change_requestR. An agent does not approve: there is no tool for deciding.
The full schema of each tool (fields, types, descriptions) is returned by tools/list.