MCP server

4.0.0

Kuvasz ships with a built-in Model Context Protocol (MCP) server, which exposes your monitoring data and management operations as tools that AI assistants can call directly. This lets you query monitor status, view incidents, and create or toggle monitors through natural language — right inside Claude, Cursor, or any MCP-compatible client.

Experimental feature

The MCP server is available as an experimental feature! The API surface (tool names and schemas) may change in future releases.

Enabling the MCP server

The MCP server is disabled by default. To enable it, refer to the relevant configuration.

Once enabled, the server is available at the /mcp endpoint of your Kuvasz instance (e.g. https://your.kuvasz.host/mcp). It uses the Streamable HTTP transport defined by the MCP specification.

Connecting AI clients

Kuvasz's MCP server speaks Streamable HTTP. Depending on your AI client's capabilities, there are two ways to connect it to the MCP server:

With streamable HTTP supportWithout streamable HTTP support

Just make sure that your client is configured to use the /mcp endpoint of your Kuvasz instance as an MCP server, and pass the API key for authentication (see below).

Clients using the STDIO transport (like Claude) can still use the MCP server, but require a local bridge to translate between Streamable HTTP and STDIO. The easiest way to achieve this is to use the mcp-remote bridge (installed via npx, no global install required):

{
  "mcpServers": {
    "kuvasz-uptime": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your.kuvasz.host/mcp",
        "--header",
        "X-API-KEY: {{ Your API key }} "
      ]
    }
  }
}

Authentication

The /mcp endpoint is protected by a dedicated MCP API key, which is separate from the REST API key. The REST API key (or a web UI / OIDC session) does not grant access to the MCP endpoint — you must configure the MCP API key to use the server. Pass it in one of the two supported ways:

X-API-KEY header: X-API-KEY: YourMcpApiKey
Bearer token: Authorization: Bearer YourMcpApiKey

Info

If you have disabled authentication entirely, the MCP endpoint is also unauthenticated.

Available tools

Read-only mode

If you have configured your monitors via YAML, the corresponding create-*, toggle-*, and delete-* tools will return an error when called. The same applies to the create-maintenance-window, toggle-maintenance-window, and delete-maintenance-window tools when maintenance windows are configured via YAML. Additionally, delete-* tools will fail if the monitor is referenced by a read-only status page. The list-*, get-*-details, get-*-stats, list-incidents, list-integrations, list-docker-hosts, and list-proxies tools are always available regardless of read-only mode. Incident notes are never configured via YAML, so the incident note tools are always available too.

This is the expected behavior, and works exactly the same as if you were to perform these operations via the REST API or dashboard.

Lists, page by page

The tools that list monitors, status pages, maintenance windows and incidents return one page at a time: 25 items by default. The result tells how many items and pages there are in total, so the assistant can ask for the next page with page. These tools can also change the page size (size), search by name (name), and sort the items (sortedBy, sortOrder).

The MCP server exposes the following tools to connected clients:

HTTP monitors

4.0.0

Tool	Description
`list-http-monitors`	List all HTTP monitors with their current uptime and SSL status
`get-http-monitor-details`	Get detailed information about an HTTP monitor by ID
`get-http-monitor-stats`	Get latency and uptime statistics (configurable look-back window)
`create-http-monitor`	Create a new HTTP monitor
`toggle-http-monitor`	Enable or disable an HTTP monitor (disabling also implicitly disables its SSL checks)
`delete-http-monitor`	Permanently delete an HTTP monitor by ID, including all its history and events

ICMP (ping) monitors

4.0.0

Tool	Description
`list-icmp-monitors`	List all ICMP monitors with their current uptime status
`get-icmp-monitor-details`	Get detailed information about an ICMP monitor by ID
`get-icmp-monitor-stats`	Get latency and packet-loss statistics (configurable look-back window)
`create-icmp-monitor`	Create a new ICMP monitor
`toggle-icmp-monitor`	Enable or disable an ICMP monitor
`delete-icmp-monitor`	Permanently delete an ICMP monitor by ID, including all its history and events

Push (heartbeat) monitors

4.0.0

Tool	Description
`list-push-monitors`	List all push monitors with their current uptime status
`get-push-monitor-details`	Get detailed information about a push monitor by ID
`get-push-monitor-stats`	Get uptime statistics (configurable look-back window)
`create-push-monitor`	Create a new push monitor
`toggle-push-monitor`	Enable or disable a push monitor
`delete-push-monitor`	Permanently delete a push monitor by ID, including all its history and events

TCP (port) monitors

4.2.0

Tool	Description
`list-tcp-monitors`	List all TCP monitors with their current uptime status
`get-tcp-monitor-details`	Get detailed information about a TCP monitor by ID
`get-tcp-monitor-stats`	Get latency and uptime statistics (configurable look-back window)
`create-tcp-monitor`	Create a new TCP monitor
`toggle-tcp-monitor`	Enable or disable a TCP monitor
`delete-tcp-monitor`	Permanently delete a TCP monitor by ID, including all its history and events

DNS monitors

4.2.0

Tool	Description
`list-dns-monitors`	List all DNS monitors with their current uptime status
`get-dns-monitor-details`	Get detailed information about a DNS monitor by ID
`get-dns-monitor-stats`	Get latency and uptime statistics (configurable look-back window)
`create-dns-monitor`	Create a new DNS monitor
`toggle-dns-monitor`	Enable or disable a DNS monitor
`delete-dns-monitor`	Permanently delete a DNS monitor by ID, including all its history and events

Docker monitors

4.5.0

Tool	Description
`list-docker-monitors`	List all Docker monitors with their current uptime status and container image
`get-docker-monitor-details`	Get detailed information about a Docker monitor by ID
`get-docker-monitor-stats`	Get CPU, memory and uptime statistics of the container (configurable look-back window)
`create-docker-monitor`	Create a new Docker monitor
`toggle-docker-monitor`	Enable or disable a Docker monitor
`delete-docker-monitor`	Permanently delete a Docker monitor by ID, including all its history and events

Status pages

4.0.0

Tool	Description
`list-status-pages`	List all status pages with their basic configuration (title, slug, visibility, monitor count, selected categories)
`get-status-page-details`	Get full details of a specific status page including per-monitor uptime status, uptime ratio, and 30-day uptime history. Like on the status pages, only the latest 20 incidents of each monitor are listed, and `incidentCount` tells how many there were in total

Maintenance windows

4.1.0

Tool	Description
`list-maintenance-windows`	List all maintenance windows with their schedule (manual, recurring or one-off) and current active state
`get-maintenance-window-details`	Get full details of a specific maintenance window, including affected monitors and categories, notified integrations, and resolved next start / end
`create-maintenance-window`	Create a new maintenance window (manual, `cron` + `duration` recurring, or `start` + `duration` one-off)
`toggle-maintenance-window`	Enable or disable a maintenance window via its master `enabled` switch
`delete-maintenance-window`	Permanently delete a maintenance window by ID

The maintenanceWindows affecting a monitor (and whether it is currently inMaintenance) are also surfaced on the get-*-monitor-details tool outputs.

Docker hosts and proxies

4.5.0

Both are defined in the YAML configuration only, so they can be listed, but not created through the MCP server. The listed names are what create-docker-monitor accepts in its dockerHost field, and what create-http-monitor and create-tcp-monitor accept in their proxy fields.

Tool	Description
`list-docker-hosts`	List the configured Docker hosts with their URL, the way Kuvasz authenticates to them, and the Engine API version negotiated so far
`list-proxies`	List the configured outbound proxies with their type (HTTP or SOCKS5), address, and whether Kuvasz authenticates to them

Integrations

4.0.0

Tool	Description
`list-integrations`	List all configured integrations with their type and settings

Application settings

4.0.0

Tool	Description
`get-app-settings`	Get the current application settings (authentication, data retention, language, metrics export, MCP server, and version info)

Incidents

4.0.0

Tool	Description
`list-incidents`	List incidents across all monitor types, optionally filtered by monitor ID, monitor name or incident type, with a configurable look-back window and resolved-flag filter
`get-incident-details`	Get the details of an incident by its type and event ID: its notes, and the integrations that were notified when it started and when it was resolved
`create-incident-note`	Add a note to an incident, with an investigation status, an optional timestamp, and an optional public flag to show it on the status pages. To change a note, delete and recreate it
`delete-incident-note`	Permanently delete an incident note

The get-incident-details tool and the incident note tools are available from version 4.5.0 on.