> ## Documentation Index > Fetch the complete documentation index at: https://docs.flashcat.cloud/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > Connect the Flashduty API to AI tools via the MCP protocol for intelligent incident management and automation in clients like Cursor and Claude. Flashduty MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 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](/en/developer/go-sdk); every tool is a thin wrapper over the Flashduty Open API. ## Use cases *** Hand incident creation, acknowledgment, and closure in Flashduty over to AI orchestration, wired into your operations workflow. Let an LLM retrieve incidents, alerts, and change records by time range, status, severity, and other criteria, and summarize them. Call Flashduty capabilities from your own AI apps to build intelligent on-call, incident retrospectives, and more. 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. 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: ```json theme={null} { "mcpServers": { "flashduty": { "url": "https://mcp.flashcat.cloud/mcp", "headers": { "Authorization": "Bearer " } } } } ``` 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. ```json theme={null} { "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](https://github.com/flashcatcloud/flashduty-mcp-server/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:** ```json theme={null} { "mcpServers": { "flashduty": { "command": "/path/to/flashduty-mcp-server", "args": ["stdio"], "env": { "FLASHDUTY_APP_KEY": "your_app_key_here" } } } } ``` **Via command-line flag:** ```json theme={null} { "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 `. | | 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
FieldDefaultDescription
`FLASHDUTY_APP_KEY`-Flashduty APP Key (required).
`FLASHDUTY_TOOLSETS`all toolsetsComma-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:** ```bash theme={null} docker run -i --rm \ -e FLASHDUTY_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): ```bash theme={null} ./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: ```json theme={null} { "mcpServers": { "flashduty": { "url": "https://mcp.flashcat.cloud/mcp?toolsets=incidents,users&read_only=true", "headers": { "Authorization": "Bearer " } } } } ``` ### Output format (TOON) The server supports outputting tool results in [TOON (Token-Oriented Object Notation)](https://github.com/toon-format/toon) 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: | 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` | 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. | | 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. | | Tool | Description | | --------------- | ------------------------------------- | | `query_members` | Query members, with optional filters. | | `query_teams` | Query teams and their member details. | | Tool | Description | | ------------------------ | ----------------------------------------------------------------- | | `query_channels` | Query channels, returning enriched data such as team and creator. | | `query_escalation_rules` | Query the escalation rules of a channel. | | 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). | | Tool | Description | | --------------- | ------------------------------- | | `query_changes` | Query change records by filter. | | Tool | Description | | -------------- | ------------------------------- | | `query_fields` | Query custom field definitions. | ## Related resources *** The Go SDK that MCP Server depends on, covering the entire Flashduty Open API. Browse the source, releases, and issue tracker.