# unikraft mcp

The server speaks the Model Context Protocol over stdin and stdout, or over
HTTP with `--listen`, so an AI assistant such as Claude Code, Claude Desktop
or Cursor can manage Unikraft Cloud through typed tools instead of shelling
out to the CLI.

Every resource type gets list, create, edit and delete tools, named like
`instance_list` or `volume_create`. A list tool also fetches specific resources
when given keys. Instances additionally get `instance_control` for start,
stop, restart and suspend, and `instance_logs`. Sandboxes get `sandbox_exec`,
`sandbox_read` and `sandbox_write` for the commands and files inside them.
The tools use the current profile and fan out across its metros exactly like
the matching CLI commands do. Every tool call reads the configuration file
again, so `unikraft login` and `unikraft profile use` take effect without
restarting the server. Unless `--profile` pins one, `profile_use` lists the
profiles and switches between them.

Pass `--resources` with a comma-separated list of resource types to serve
only their tools, such as `--resources instance,volume,metro`. The names
are the prefixes of the tool names. A shorter tool list costs an assistant
less context on every turn.

The documentation is served as resources: `unikraft://docs` is the table of
contents and `unikraft://docs/<path>` a page, such as `unikraft://docs/cli/fields`.
Pages are fetched from the documentation site when read, so they cost
nothing until an assistant asks for one.

Diagnostics always go to stderr, because stdout carries the protocol in stdio
mode. Raise them with `--log-level debug`. A `--timeout` ends the whole
session when it expires.

Register the server with a client as a stdio server, for example:

    \{"mcpServers": \{"unikraft": \{"command": "unikraft", "args": ["mcp"]\}\}\}

With `--listen host:port` the same tools are served over HTTP at `/mcp`, with
a liveness check at `/healthz`, still using this profile's credentials. Pass
`--tls-cert` and `--tls-key` to serve HTTPS instead. Only loopback addresses
are accepted unless `--allow-remote` is given. TLS encrypts the traffic but
does not authenticate clients, so then put an authenticating proxy in front,
since every client acts as you. A `--timeout` then stops accepting requests
and drains the calls in flight. Clients register the server by URL:

    \{"mcpServers": \{"unikraft": \{"type": "http", "url": "http://127.0.0.1:8080/mcp"\}\}\}


```
unikraft mcp [flags]
```

## Examples

Serve every tool over stdio:

```bash
unikraft mcp
```

Serve only the tools that cannot change anything:

```bash
unikraft mcp --read-only
```

Serve only the instance, volume and metro tools:

```bash
unikraft mcp --resources instance,volume,metro
```

Serve another profile with debug logs on stderr:

```bash
unikraft mcp --profile staging --log-level debug
```

Serve over HTTP on the loopback interface:

```bash
unikraft mcp --listen 127.0.0.1:8080
```

Serve HTTPS on every interface with a certificate:

```bash
unikraft mcp --listen :8443 --allow-remote --tls-cert cert.pem --tls-key key.pem
```

Serve every interface on an instance whose service terminates TLS:

```bash
unikraft mcp --listen :8080 --allow-remote
```

## Options

```
  --allow-remote              Let --listen bind a non-loopback address. Every client then acts with this profile's credentials, so only do this behind an authenticating proxy or on a private network.
  --listen host:port          Serve the protocol over HTTP at this address, at /mcp, instead of stdio. Loopback addresses only unless --allow-remote is set.
  --read-only                 Expose only the tools that cannot change anything: list, image_get, instance_logs and sandbox_read.
  --resources type,...        Serve only the tools of these resource types. The names are the prefixes of the tool names. Defaults to every type.
  --tls-cert file             Serve --listen over HTTPS with this PEM certificate chain.
  --tls-key file              PEM private key of --tls-cert.
```

## Options inherited from parent commands

```
  --config file               Path to the configuration file.
  --log-level level           Set the logging level. (default info)
  --log-type type             Set the log type. (default text)
  --profile name              Set the current profile.
  --telemetry                 Toggle usage analytics. (default true)
  --timeout duration          Set a deadline for the command (e.g. 30s, 5m, 1h).
```

## See Also

* [`unikraft`](../unikraft.mdx): The Unikraft Command-Line Interface.