AI assistants (MCP)

Connect Claude Code, Claude Desktop, Cursor and other MCP clients to Kowan, so AI assistants can inspect and operate your Docker hosts within an API key's role.

Kowan includes a Model Context Protocol server, so AI assistants such as Claude Code, Claude Desktop and Cursor can inspect and operate your Docker hosts. An assistant works with the permissions of the API key you give it, and every change it makes is written to the audit log. There is nothing extra to install on the server.

Ask, for example, "what's crashing on my servers?" or "show me the last errors of the api container on host nas".

How it works

Endpoint

Your Kowan URL followed by /mcp, such as https://kowan.example.com/mcp.

Transport

Streamable HTTP.

Authentication

An API key, sent as Authorization: Bearer pk_.... A sign-in token works too.

Local bridge

kowanctl mcp, for clients that only start local processes.

Settings > AI assistants in the console shows your endpoint, ready-to-paste setups for Claude Code, Claude Desktop and Cursor, and the tools your role can call.

Create an API key

Give each assistant its own API key, with the lowest role that does the job. An admin creates it in Settings > API keys, or from a terminal:

kowanctl apikey create claude --role viewer

The key's role decides which tools the assistant sees:

A key bound to a team or to specific scopes only sees and acts on what those grants cover. For an assistant that should only look, a viewer key is the safe choice.

Connect a client

In the examples, replace https://kowan.example.com with your Kowan URL and pk_... with the API key.

Claude Code

Run in a terminal:

claude mcp add --transport http kowan https://kowan.example.com/mcp \
  --header "Authorization: Bearer pk_..."

Claude Desktop

Claude Desktop starts MCP servers as local processes. Install kowanctl, then add Kowan to claude_desktop_config.json:

{
  "mcpServers": {
    "kowan": {
      "command": "kowanctl",
      "args": ["mcp"],
      "env": {
        "KOWAN_URL": "https://kowan.example.com",
        "KOWAN_API_KEY": "pk_..."
      }
    }
  }
}

kowanctl mcp reads messages on standard input, forwards each one to your Kowan server and writes the replies on standard output. If the server restarts, it opens a new session on its own.

If Claude Desktop cannot find kowanctl, set command to its absolute path, such as the output of which kowanctl.

The bridge takes the server URL from --url, then KOWAN_URL, then the usual kowanctl configuration. It takes the credential from --api-key, then KOWAN_API_KEY, then the usual configuration, then your kowanctl login token. See Command line.

Cursor and other clients

Any client that supports remote MCP servers over HTTP with custom headers (Cursor, Windsurf, VS Code and others) takes the URL and an Authorization header. For Cursor, in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "kowan": {
      "url": "https://kowan.example.com/mcp",
      "headers": { "Authorization": "Bearer pk_..." }
    }
  }
}

Clients that only start local processes use the kowanctl mcp setup shown for Claude Desktop.

Safety

Same rules as the API

The assistant authenticates like any API client, and its role and grants apply exactly as in the REST API. It only sees the tools its role allows, and Kowan checks the role again on every call.

Confirmation for destructive tools

Tools that delete something (marked destructive below) do nothing unless the call includes confirm: true. Without it, Kowan tells the assistant to confirm with you first. Clients that honor the MCP destructive hint also ask you before running them.

Audit log

Every call to a tool that changes something is written to the audit log with the action MCP, the path /mcp/tools/<tool>, the key or user that made it, and the arguments. Compose files, container specs and template values are replaced by placeholders. Calls refused for lack of role are logged too.

No secrets in answers

Container inspection returns environment variable names, never their values. Deployments hide environment values and webhook secrets; a revision shows them only to a role that can operate the deployment.

Bounded answers

Logs return 200 lines by default and 2,000 at most, lists are paged, and every answer is capped at 64 KiB with a note saying what was cut.

Tools

Every tool that takes a host accepts a host ID or name, and defaults to local.

Fleet and workloads

Containers

Images, volumes and networks

Deployments

Logs and events

Monitoring and automation

Maintenance

Resources and prompts

Clients that support MCP resources can read these as JSON: kowan://fleet/summary, kowan://hosts, kowan://alerts/open, kowan://deployments and kowan://hosts/{host}/containers.

Three prompts are ready to use: diagnose_container (a container and optional host), fleet_health_report, and update_review (an optional host).

Limitations

• Sessions live in the server's memory and expire after 12 hours without use. After a server restart, clients start a new session.
• A long tool call, such as an image pull, holds its request until it finishes. The server sends no progress updates.
• There is no OAuth sign-in flow: the client must send the API key as a header, or use kowanctl mcp.
• A web page can call the endpoint only from Kowan's own origin, KOWAN_EXTERNAL_URL, or an origin listed in KOWAN_MCP_ALLOWED_ORIGINS. Clients that are not browsers are not affected. See Configuration.