Using the Avassa MCP Server with AI Assistants

supctl includes a built-in Model Context Protocol (MCP) server that lets AI assistants connect directly to your Control Tower. Once configured, you can ask your AI assistant to inspect cluster health, diagnose application failures, tail recent alerts, and propose configuration changes - without manually running supctl commands and pasting output.

The MCP server works with any MCP-compatible client, including Claude Code, Claude Desktop, ChatGPT, Codex, Cursor, Zed, and others.

Prerequisites

supctl installed and logged in to your Control Tower (see Installing supctl)
An MCP-compatible AI client (see Client setup below)

Client setup

The MCP server is started by running supctl mcp start-server. Each client has its own way of configuring MCP servers, but the command is the same in all cases.

Claude Code

Add an .mcp.json file to your project root (or any working directory where you use Claude Code):

{
  "mcpServers": {
    "supd": {
      "type": "stdio",
      "command": "supctl",
      "args": ["mcp", "start-server"]
    }
  }
}

When you open a project containing .mcp.json, Claude Code automatically spawns supctl mcp start-server as a background subprocess. Claude Code will prompt you to approve the server the first time it is used.

Claude Desktop

Edit the Claude Desktop configuration file and add the supd server under mcpServers:

{
  "mcpServers": {
    "supd": {
      "command": "supctl",
      "args": ["mcp", "start-server"]
    }
  }
}

The configuration file is located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after saving the file. The supd server will appear in the tools panel (the hammer icon) when a conversation starts.

Note: Claude Desktop launches the MCP server using the environment of the desktop application, which may differ from your terminal environment. If supctl is not on the system PATH, use the full path to the binary (e.g. /usr/local/bin/supctl).

Codex

Add the server to your Codex configuration file (~/.codex/config.yaml):

mcpServers:
  supd:
    type: stdio
    command: supctl
    args:
      - mcp
      - start-server

Codex spawns supctl mcp start-server as a subprocess and communicates with it over stdin/stdout. The tools are available automatically when you start a Codex session.

ChatGPT

ChatGPT uses the HTTP transport, so you need to start the MCP server manually before connecting:

supctl mcp start-server --http --port 8765

Keep this process running while using ChatGPT. The server listens on http://127.0.0.1:8765 by default; use --port to choose a different port and --bind to listen on a different address.

In ChatGPT, go to Settings > Connectors (or the equivalent MCP configuration section for your plan) and add a new MCP server pointing to the URL where your supctl mcp start-server --http process is reachable. For the ChatGPT desktop app, use http://127.0.0.1:8765. For the web interface, the server must be reachable from ChatGPT's servers - expose it via a reverse proxy or tunnel and use that public URL.

Authentication, TLS, and CORS

The HTTP server defaults to binding only on 127.0.0.1. To listen on a non-localhost address, you must provide a Bearer token; the server refuses to start otherwise.

# Generate a random token and require it in the Authorization header:
TOKEN=$(openssl rand -hex 32)
supctl mcp start-server --http --bind 0.0.0.0 --auth-token "$TOKEN"

# Or read the token from a file:
supctl mcp start-server --http --bind 0.0.0.0 --auth-token-file /etc/supctl-mcp.token

# Serve TLS directly instead of using a reverse proxy:
supctl mcp start-server --http --bind 0.0.0.0 \
    --auth-token "$TOKEN" \
    --cert /etc/ssl/private/mcp.pem \
    --key /etc/ssl/private/mcp.key

# Allow a browser-based MCP client at a specific origin:
supctl mcp start-server --http --allow-origin https://chat.example.com

Clients then send Authorization: Bearer <token> on every request.

Cursor

Add a .cursor/mcp.json file to your project root:

{
  "mcpServers": {
    "supd": {
      "command": "supctl",
      "args": ["mcp", "start-server"]
    }
  }
}

Alternatively, configure it globally via Cursor Settings > MCP. Cursor picks up the server automatically and makes the tools available to the AI in the editor panel.

Zed

Add the server to your Zed settings.json under the context_servers key:

{
  "context_servers": {
    "supd": {
      "command": {
        "path": "supctl",
        "args": ["mcp", "start-server"]
      }
    }
  }
}

Other MCP-compatible clients

Any client that supports MCP stdio servers can use supctl mcp start-server. The general pattern is to configure the client to run supctl mcp start-server as a subprocess communicating over stdin/stdout. Consult your client's MCP documentation for the exact configuration format.

Active profile

The MCP server uses whichever supctl profile is currently active. If you work with multiple Control Towers, switch profiles before starting your AI client:

supctl profile switch my-production-profile

For desktop applications (Claude Desktop, Cursor, Zed), set the desired profile before launching the application, or configure a dedicated profile and point SUPCTL_PROFILE_DIR to its directory in the client's environment if the client supports environment variable configuration.

How it works

Stdio transport (Claude Code, Claude Desktop, Codex, Cursor, Zed): The AI client spawns supctl mcp start-server as a subprocess and communicates with it over stdin/stdout using the MCP protocol.

HTTP transport (ChatGPT): You start supctl mcp start-server --http manually as a long-running process. The AI client sends JSON-RPC requests over HTTP POST to the server's endpoint.

In both cases, the MCP server makes REST API calls to your Control Tower on the AI's behalf, using the same Bearer token authentication as regular supctl commands.

The connection is local to your machine - no Control Tower data is sent to the AI provider except what appears in the conversation itself.

The server reports the connected Control Tower host and tenant name in its initialization response, so the AI knows the context without having to call a tool first. It supports MCP protocol versions 2025-03-26 and 2024-11-05, negotiating with the client at connection time.

Available tools

The MCP server exposes the following tools:

Observability

Tool	Description
`show`	Fetch any operational state or configuration path (use `get_model` or `search_model` first to discover the correct path)
`get_cluster_health`	Call-home state, cluster establishment, distress indicators, versions
`get_sites`	List all assigned sites with their connection state
`get_site_health`	Per-site or all-sites: connected, degraded, deployed-application count
`get_application_status`	Application health summary or per-application status
`get_application_health`	Per-application operational status, error messages, and per-site breakdown
`get_deployment_status`	Deployment stage, site counts, and deploying-status summary or per application
`get_alerts`	Recent alerts from the system notifications stream (last hour by default, optional `site` filter)
`get_logs`	Recent application log entries (last hour by default, optional `site` filter)
`get_container_logs`	Container stdout/stderr (the actual logs the running container produced) for a given application on a given site. Returns each entry with `time`, `site`, `host`, `service`, `service_instance`, `container`, and `payload`. If empty, the response includes a diagnostic hint.
`list_app_containers`	Discover the service-instance + container combinations that exist for an application by listing container-log topics. Call this when you do not yet know which services/containers an application has, or when `get_container_logs` returns empty.
`get_volga_topics`	List available event stream topics for the current tenant (use before `get_logs` to discover topic names)
`get_acme_requests`	ACME certificate requests with status, expiry, and errors

Actions

Tool	Description
`delete_acme_request`	Delete a specific ACME certificate request

Staging

Tool	Description
`stage_change`	Append a proposed configuration change to the staging file in the active profile directory. Data is validated against the Control Tower schema before staging - an error is returned if the data is invalid.
`show_staged`	Display the current staged changes
`delete_staged_change`	Remove a single staged change by its 1-based index (use `show_staged` first to see the list)
`clear_staged`	Discard all staged changes

Model exploration

Tool	Description
`get_model`	Navigate the data model schema to a given path and list its children with their kinds and descriptions. Use this to discover what paths exist before calling `show` or `stage_change`.
`search_model`	Search the full data model by keyword, matching path names and descriptions. Returns matching paths with `{key}` placeholders for list nodes to show where key values are required.

Documentation

Tool	Description
`get_docs`	Search the Avassa documentation index by keyword and return matching topics with URLs.
`read_doc`	Fetch the full markdown content of a docs.avassa.io page returned by `get_docs`. URLs outside `https://docs.avassa.io/` are rejected.

The staging tools only write a local file - no changes are sent to the Control Tower until you review and apply them yourself. The staging file is locked while it is being read or written so concurrent stage_change calls (and concurrent supctl mcp staged invocations) serialise safely.

Slash commands

In addition to tools, the MCP server exposes a small set of prompts that appear as slash commands in clients that support them (for example /diagnose-site in Claude Code):

Prompt	Arguments	What it does
`diagnose-site`	`site` (optional)	Walks site health, application health, recent alerts, and container logs for one or all sites and summarises the findings.
`check-certificates`	none	Audits ACME certificate requests for failures, expiring certificates, and unresolved errors.
`recent-alerts`	`since` (optional, default `1h`), `site` (optional)	Summarises recent alerts grouped by type and severity.
`deployment-status`	`application` (optional)	Reports deployment health, highlighting stalls and per-site failures.

Each prompt expands into a guided sequence of tool calls; the AI will explain what it finds rather than make any changes.

Resources

In clients that show MCP resources (subscribable read-only snapshots), the server exposes:

URI	Description
`supd://state/sites`	All assigned sites with connection state
`supd://state/alerts/recent`	Alerts from the last hour
`supd://state/deployments`	Deployment status across applications
`supd://state/cluster-health`	Call-home state, versions, distress indicators

Resources return JSON snapshots; the AI can use them as context without having to invoke a tool explicitly.

Proposing configuration changes

The staging workflow lets the AI propose configuration changes that you review before they are applied to the Control Tower.

The workflow works like this:

You ask the AI to propose a configuration change - for example, "Update the default image registry to my-registry.example.com and stage it for me to review."
The AI calls stage_change, which validates the proposed data against the Control Tower schema and appends the change to a local .supctl-staged.yaml file as a staged transaction.
You review the proposals with supctl mcp staged show.
When satisfied, you apply all changes at once with supctl mcp staged apply, or discard them with supctl mcp staged clear.

How it works

When the AI calls stage_change, the data payload is first validated against the Control Tower's schema. If validation fails, the error is returned to the AI so it can correct the data before staging. Once validated, the change is appended to a .supctl-staged.yaml file in the active profile directory. The file records the target host and tenant alongside each change:

target:
  host: ct.example.com
  tenant: acme
changes:
  - description: "Set custom image registry"
    method: merge
    path:
      - image-registry
      - settings
    data: |
      default-remote-registry: my-registry.example.com
  - description: "Deploy monitoring application"
    method: create
    path:
      - application-deployments
    data: |
      name: monitoring
      ...

Reviewing and applying staged changes

Once the AI has staged its proposals, you review and apply them using supctl mcp staged from a terminal:

# Review what the AI has proposed
supctl mcp staged show

# Apply all staged changes to the Control Tower
supctl mcp staged apply

# Discard staged changes without applying
supctl mcp staged clear

supctl mcp staged apply sends all changes as a single transactional request - either all changes are applied or none are. On full success it removes the staging file automatically. The file is kept if the request fails, so you can inspect the changes and retry.

Example usage

Once configured, you can interact with your cluster conversationally. Some examples:

Checking site and application health:

"Are all sites connected? Which applications are currently failing?"

Diagnosing a problem:

"Show me the recent alerts and application logs for the last hour."

Diagnosing a certificate issue:

"Check the ACME certificate requests and tell me if any have errors."

Proposing a configuration change:

"Update the default image registry to my-registry.example.com and stage the change for me to review."

The AI will call the appropriate tools, interpret the results, and explain what it finds - including suggesting follow-up actions and staging configuration changes where relevant.

Security considerations

The MCP server authenticates to the Control Tower with the same token and permissions as the active supctl profile. It is subject to the same access controls enforced by the Control Tower, including tenant isolation and policy checks. Anything the active profile can read or stage, the AI can read or stage.

The MCP server only exposes read tools and staging tools. No configuration is changed on the Control Tower until you explicitly run supctl mcp staged apply from your terminal.

Logs and alerts may contain sensitive data. get_alerts, get_logs, and get_container_logs return real cluster output; that output then becomes part of your AI conversation and may be sent to the AI provider as conversation context. Only enable the MCP server in environments where this is acceptable.

HTTP transport hardening. The --http mode binds to 127.0.0.1 by default. To expose the server beyond localhost:

Always pass --auth-token (or --auth-token-file); the server refuses to start on a non-localhost bind without authentication.
Prefer --cert / --key for direct TLS over running behind a reverse proxy when you need to terminate TLS yourself.
Only set --allow-origin for trusted browser-based clients, and use a specific origin rather than *.

Troubleshooting

The supd server does not appear in the client

Check that the configuration file is valid JSON and saved in the correct location for your client. For Claude Code, verify that .mcp.json exists in the project root. For Claude Desktop, restart the application after editing the configuration file.

For Claude Code, you can reset the server approval state with:

claude mcp reset-project-choices

supctl not found

Desktop applications (Claude Desktop, Cursor, Zed) may use a different PATH than your terminal. Use the full path to supctl in the configuration, for example:

"command": "/usr/local/bin/supctl"

Run which supctl in your terminal to find the full path.

Authentication errors from the MCP server

Run supctl show system from the same terminal to verify your profile is logged in and can reach the Control Tower. If not, re-authenticate:

supctl profile switch <your-profile>

supctl mcp staged apply fails with an error

All changes are applied as a single transaction - if any change fails, none are applied. The staging file is kept in your active profile directory so you can review and fix the changes, then run supctl mcp staged apply again.

Prerequisites​

Client setup​

Claude Code​

Claude Desktop​

Codex​

ChatGPT​

Authentication, TLS, and CORS​

Cursor​

Zed​

Other MCP-compatible clients​

Active profile​

How it works​

Available tools​

Observability​

Actions​

Staging​

Model exploration​

Documentation​

Slash commands​

Resources​

Proposing configuration changes​

How it works​

Reviewing and applying staged changes​

Example usage​

Security considerations​

Troubleshooting​

Prerequisites

Client setup

Claude Code

Claude Desktop

Codex

ChatGPT

Authentication, TLS, and CORS

Cursor

Zed

Other MCP-compatible clients

Active profile

How it works

Available tools

Observability

Actions

Staging

Model exploration

Documentation

Slash commands

Resources

Proposing configuration changes

How it works

Reviewing and applying staged changes

Example usage

Security considerations

Troubleshooting