GigakubeWikigigakube.ch →Menu ↓

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:

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:

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

The tools

In the list: R only reads, W writes, D destroys (no undo). The minimum role is in brackets.

Project, catalog, costs

Servers

Firewall

Addresses and networks

Kubernetes

Imports (where the zone offers them)

Replication to another zone (where the zone offers it)

Protection

DNS

Change requests

The full schema of each tool (fields, types, descriptions) is returned by tools/list.