MCP Server - Flashduty Docs

Flashduty MCP Server is a Model Context Protocol (MCP) server that connects the Flashduty API seamlessly into MCP-capable AI tools (such as Cursor and Claude Desktop). With it, you can let an LLM query, acknowledge, and close incidents, retrieve channels and members, and validate notification templates directly — embedding incident management and automation into your AI workflow.

Flashduty MCP Server is built on the go-flashduty SDK; every tool is a thin wrapper over the Flashduty Open API.

Use cases

Automate incident workflows

Hand incident creation, acknowledgment, and closure in Flashduty over to AI orchestration, wired into your operations workflow.

Data extraction & analysis

Let an LLM retrieve incidents, alerts, and change records by time range, status, severity, and other criteria, and summarize them.

Build AI ops tools

Call Flashduty capabilities from your own AI apps to build intelligent on-call, incident retrospectives, and more.

Template validation & debugging

Validate rendering and query available variables and functions in real time while editing notification templates.

Deployment

Flashduty MCP Server offers three deployment modes; choose based on your MCP client’s capabilities and your runtime environment.

Remote service (recommended)
Docker
Build from source

No local installation needed — connect directly to the official remote instance https://mcp.flashcat.cloud/mcp, authenticating with your APP Key via Authorization: Bearer. This is the fastest way to get started.For Cursor, add to your MCP configuration:

{
  "mcpServers": {
    "flashduty": {
      "url": "https://mcp.flashcat.cloud/mcp",
      "headers": {
        "Authorization": "Bearer <your_flashduty_app_key>"
      }
    }
  }
}

The remote service supports only Streamable HTTP transport (POST /mcp). Check your MCP client’s documentation for the exact syntax and location of remote MCP service configuration.

Run locally via Docker, authenticating with the FLASHDUTY_APP_KEY environment variable over stdio transport.

{
  "mcpServers": {
    "flashduty": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "FLASHDUTY_APP_KEY",
        "registry.flashcat.cloud/public/flashduty-mcp-server"
      ],
      "env": {
        "FLASHDUTY_APP_KEY": "your_flashduty_app_key"
      }
    }
  }
}

Download a prebuilt release from GitHub Releases, or build it yourself with go build in the cmd/flashduty-mcp-server directory. The APP Key can be supplied via an environment variable or a command-line flag.Via environment variable:

{
  "mcpServers": {
    "flashduty": {
      "command": "/path/to/flashduty-mcp-server",
      "args": ["stdio"],
      "env": {
        "FLASHDUTY_APP_KEY": "your_app_key_here"
      }
    }
  }
}

Via command-line flag:

{
  "mcpServers": {
    "flashduty": {
      "command": "/path/to/flashduty-mcp-server",
      "args": ["stdio", "--app-key", "your_app_key_here"]
    }
  }
}

Authentication and transport

Item	Description
Auth (local)	Provide the Flashduty APP Key via the `FLASHDUTY_APP_KEY` environment variable or the `--app-key` command-line flag.
Auth (remote)	Provide the APP Key via the request header `Authorization: Bearer <your_flashduty_app_key>`.
Streamable HTTP	`flashduty-mcp-server http`, endpoint `POST /mcp`. The official remote instance is `https://mcp.flashcat.cloud/mcp`.
stdio	`flashduty-mcp-server stdio`, for local clients such as Cursor and Claude Desktop.

The server does not support the legacy standalone SSE transport (a separate GET /sse endpoint) and returns 405 Method Not Allowed for GET requests. Streamable HTTP already streams responses over POST per the MCP spec — use it directly; if your client only supports legacy SSE, upgrade the client or switch to stdio locally.

Configuration

Flashduty MCP Server supports toolset trimming, read-only mode, output format, and other settings to suit different scenarios. Local deployments are configured via environment variables or command-line flags; the remote service is configured dynamically by appending query parameters to the URL.

Environment variables

Field	Default	Description
`FLASHDUTY_APP_KEY`	-	Flashduty APP Key (required).
`FLASHDUTY_TOOLSETS`	all toolsets	Comma-separated list of enabled toolsets (e.g. `incidents,users,channels`); use `all` to enable everything.
`FLASHDUTY_READ_ONLY`	`false`	Enable read-only mode (`1` or `true`), keeping only query tools and forbidding any write operations.
`FLASHDUTY_OUTPUT_FORMAT`	`json`	Tool result output format, either `json` or `toon`.
`FLASHDUTY_BASE_URL`	`https://api.flashcat.cloud`	Base URL of the Flashduty API.

Enable only the toolsets you need — it helps the LLM choose tools more accurately and reduces context size. Read-only mode improves safety in read-only scenarios such as data analysis and on-call inspection.

Docker example:

docker run -i --rm \
  -e FLASHDUTY_APP_KEY=<your-app-key> \
  -e FLASHDUTY_TOOLSETS="incidents,users,channels" \
  -e FLASHDUTY_READ_ONLY=1 \
  registry.flashcat.cloud/public/flashduty-mcp-server

Command-line flags

When building from source and running the binary directly, you can use the following flags (which take precedence over the env vars of the same name):

./flashduty-mcp-server stdio \
  --app-key your_app_key_here \
  --toolsets incidents,users,channels \
  --read-only \
  --output-format toon

--app-key: Flashduty APP Key (equivalent to FLASHDUTY_APP_KEY).
--toolsets: comma-separated list of enabled toolsets.
--read-only: enable read-only mode.
--output-format: tool result output format (json or toon).
--base-url: base URL of the Flashduty API.

Remote service configuration

When using the official remote instance, append query parameters to the URL to configure toolsets and read-only mode dynamically:

{
  "mcpServers": {
    "flashduty": {
      "url": "https://mcp.flashcat.cloud/mcp?toolsets=incidents,users&read_only=true",
      "headers": {
        "Authorization": "Bearer <your_flashduty_app_key>"
      }
    }
  }
}

Output format (TOON)

The server supports outputting tool results in TOON (Token-Oriented Object Notation) format. For arrays of objects with uniform fields (such as member lists or incident lists), TOON can cut token usage by 30%–50% compared with JSON, and modern LLMs can parse it directly. Set FLASHDUTY_OUTPUT_FORMAT=toon (or --output-format toon) to enable it.

Toolsets and tools

The server provides 8 toolsets and 23 tools in total, all enabled by default. The table below summarizes each toolset:

Toolset	Tools	Description
`incidents`	8	Full incident lifecycle management and queries
`status_page`	4	Status Page management
`templates`	4	Notification template validation and variable / function queries
`users`	2	Member and team queries
`channels`	2	Channel and escalation rule queries
`alerts`	1	Alert raw-event query
`changes`	1	Change record query
`fields`	1	Custom field definition query

Toolset names (incidents, status_page, etc.) are internal program identifiers; keep them in English when configuring.

The tools in each toolset are as follows:

incidents — incident lifecycle management (8 tools)

Tool	Description
`query_incidents`	Query incidents by ID, short number, time range, status, severity, channel, or free text, returning the incident list and each incident’s total alert count.
`query_incident_timeline`	Query an incident’s timeline events (creation, assignment, acknowledgment, resolution, notification, etc.). Each event includes `created_at` (RFC3339) and `creator_id` (the actor’s numeric ID; 0 means a system action). Call `query_members` with those IDs to resolve display names.
`query_incident_alerts`	Query alerts associated with an incident, returning title, severity, status, and labels.
`create_incident`	Create an incident, specifying title and severity, optionally assigning it to a channel or responders.
`update_incident`	Update an incident’s built-in fields (title, description, severity, impact, root cause, resolution) and custom fields, updating only the provided fields.
`ack_incident`	Acknowledge an incident, moving its status from “Triggered” to “Processing.”
`close_incident`	Close (resolve) an incident, moving its status to “Closed.”
`list_similar_incidents`	Find similar historical incidents, for reviewing past handling and identifying recurring problems.

query_incidents parameter reference

Parameter	Type	Description
`incident_ids`	string	Comma-separated full incident IDs for direct lookup. When provided, all other filters are ignored.
`nums`	string	Comma-separated short incident IDs (the 6-char number shown in the UI, e.g. `311510`). Matched within the `since`/`until` window; the backend caps a single lookup to ~30 days, so incidents older than that must be queried by their full `incident_id`.
`since`	string	Query start time (see time format reference below).
`until`	string	Query end time (see time format reference below).
`progress`	string	Filter by status: `Triggered`, `Processing`, `Closed`. Comma-separated for multiple values.
`severity`	string	Filter by severity: `Info`, `Warning`, `Critical`.
`channel_ids`	string	Comma-separated channel IDs.
`query`	string	Free-text search across title, labels, and content.
`limit`	number	Number of results to return. Default 20, max 100.

since / until time-window behavior

Both omitted: defaults to the last 30 days (convenient for querying current/open incidents).
Only since provided: queries from that time through the current moment.
Only until provided: not allowed — returns an error (since is required when until is set; omit both to use the 30-day default).
Both provided: queries the specified range; the backend hard-caps the span at ~30 days.

Accepted time formats for since and until:

Relative duration: 30d, 24h, 168h (meaning “this far before now”)
RFC3339 with timezone: 2026-04-01T10:00:00+08:00 or 2026-04-01T10:00:00Z (SDK-emitted timestamps can be passed back directly as filter bounds)
Date: 2026-04-01 (parsed as local midnight)
Datetime: 2026-04-01 10:00:00 or 2026-04-01T10:00:00 (local time)
Unix timestamp: 1712000000

status_page — status page management (4 tools)

Tool	Description
`query_status_pages`	Query status pages and their full configuration.
`list_status_changes`	List active (in-progress, non-terminal) change events on a status page — either incidents or maintenance windows. Resolved or completed historical events are not returned.
`create_status_incident`	Create an event on a status page.
`create_change_timeline`	Append a timeline update to a status page change.

templates — notification templates (4 tools)

Tool	Description
`get_preset_template`	Get the preset (default) notification template for a given channel, returning Go template code you can use as a customization starting point.
`validate_template`	Validate a notification template: parse and render it with incident data, returning a render preview, validation status, and size info; supports mock data or a real preview based on `incident_id`.
`list_template_variables`	List all variables available in notification templates, returning a variable structure with type, description, and example value.
`list_template_functions`	List all functions available in notification templates, including Flashduty custom functions and common Sprig functions.

users — member and team queries (2 tools)

Tool	Description
`query_members`	Query members, with optional filters.
`query_teams`	Query teams and their member details.

channels — channels and escalation rules (2 tools)

Tool	Description
`query_channels`	Query channels, returning enriched data such as team and creator.
`query_escalation_rules`	Query the escalation rules of a channel.

alerts — alert event query (1 tool)

Tool	Description
`query_alert_events`	Query a single alert’s raw events, returning the upstream event stream that produced the alert (such as each Prometheus firing).

changes — change record query (1 tool)

Tool	Description
`query_changes`	Query change records by filter.

fields — custom fields (1 tool)

Tool	Description
`query_fields`	Query custom field definitions.

go-flashduty SDK

The Go SDK that MCP Server depends on, covering the entire Flashduty Open API.

GitHub repository

Browse the source, releases, and issue tracker.

​Use cases

Automate incident workflows

Data extraction & analysis

Build AI ops tools

Template validation & debugging

​Deployment

​Authentication and transport

​Configuration

​Environment variables

​Command-line flags

​Remote service configuration

​Output format (TOON)

​Toolsets and tools

​Related resources

go-flashduty SDK

GitHub repository

Use cases

Deployment

Authentication and transport

Configuration

Environment variables

Command-line flags

Remote service configuration

Output format (TOON)

Toolsets and tools

Related resources