Flashduty MCP Server

English | 中文

The Flashduty MCP Server is a Model Context Protocol (MCP) server that provides seamless integration with Flashduty APIs, enabling advanced incident management and automation capabilities for developers and tools.

[!NOTE] Curated by design. This server exposes a small, task-oriented toolset rather than mirroring the full Flashduty Open API — large 1:1 tool catalogs bloat model context and degrade tool selection. For 1:1 coverage of every open API operation, use the Flashduty CLI; AI agents with shell access can drive it directly.

Use Cases

• Automating Flashduty workflows and processes.
• Extracting and analyzing data from Flashduty.
• Building AI-powered tools and applications that interact with Flashduty.

Supported Transports

If your MCP host only supports the legacy SSE transport, upgrade the host or use stdio locally.

Remote Flashduty MCP Server

The remote Flashduty MCP Server provides the easiest method for getting up and running with Flashduty integration. If your MCP host does not support remote MCP servers, you can use the local version of the Flashduty MCP Server instead.

Prerequisites

1. An MCP host that supports the latest MCP specification and remote servers, such as Cursor.
2. A Flashduty account. Hosts that support MCP OAuth sign you in through the browser; other hosts need a Flashduty APP key.

Installation

With OAuth (claude.ai, Claude Desktop, ChatGPT connectors)

Add a custom connector with the URL https://mcp.flashcat.cloud/mcp and no credentials. The host discovers the Flashduty authorization server, opens a Flashduty consent page in your browser, and acts as you through the Flashduty Open API, the same access an APP key grants.

For example, with Cursor:

For Cursors that support Remote MCP, use the following configuration:

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

Note: Refer to your MCP host's documentation for the correct syntax and location for remote MCP server setup. Requests with neither an OAuth token nor an APP key receive 401 with a WWW-Authenticate header pointing to /.well-known/oauth-protected-resource/mcp.

Local Flashduty MCP Server

Prerequisites

1. To run the server in a container, you will need to have Docker installed and running.
2. You will need a Flashduty APP key from your Flashduty account.

Installation

For example, with Cursor:

Using Docker

Add the following JSON block to your Cursor MCP configuration.

{
  "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"
      }
    }
  }
}

Using binary

Besides building from source, you can also download a pre-compiled version for your operating system directly from the project's GitHub Releases, which is a faster and more convenient option.

If you prefer to build from source, you can use go build to build the binary in the cmd/flashduty-mcp-server directory. You can provide the APP key either via environment variable or command-line argument.

You should configure your MCP host to use the built executable as its command. For example:

Via Environment Variable:

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

Via Command-line Argument:

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

Tool Configuration

The Flashduty MCP Server supports several configuration options for different use cases. The main options include:

• Toolsets: Allows you to enable or disable specific groups of functionalities. Enabling only the toolsets you need can help the LLM with tool choice and reduce the context size.
• Read-Only Mode: Restricts the server to read-only operations, preventing any modifications and enhancing security.
• i18n: Supports customizing tool descriptions to suit different languages or team preferences.

Configuration methods are divided into Remote Service Configuration and Local Service Configuration.

Remote Server Configuration

When using the public remote service (https://mcp.flashcat.cloud/mcp), you can dynamically configure it by appending query parameters to the URL.

Configuration Example

Here is an example of configuring the remote service, specifying toolsets and read-only mode:

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

• headers.Authorization: Your Flashduty APP key for authentication, prefixed with Bearer . Omit it when the host signs in with OAuth.
• toolsets=...: Use a comma-separated list to specify the toolsets to enable (e.g., incidents,users,channels).
• read_only=true: Enables read-only mode.

Local Server Configuration

When running the service locally via Docker or from source, you have full configuration control.

1. Via Environment Variables

This is the most common method for local configuration, especially in a Docker environment.

Docker Example:

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

Note: The TZ environment variable controls the timezone used for log timestamps. If not set, the server will use the system default timezone, or fall back to Asia/Shanghai in containers without timezone data (e.g., distroless images). Common timezone values include Asia/Shanghai, America/New_York, Europe/London, UTC, etc.

2. Via Command-Line Arguments

If you build and run the binary directly from the source, you can use command-line arguments.

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

Available command-line arguments:

• --app-key: Flashduty APP key (alternative to FLASHDUTY_APP_KEY environment variable)
• --toolsets: Comma-separated list of toolsets to enable
• --read-only: Enable read-only mode
• --output-format: Output format for tool results (json or toon)
• --base-url: Flashduty API base URL
• --log-file: Path to log file
• --enable-command-logging: Enable command logging
• --export-translations: Save translations to a JSON file

Note: Command-line arguments take precedence over environment variables. For toolsets configuration, if both FLASHDUTY_TOOLSETS environment variable and --toolsets argument are set, the command-line argument takes priority.

3. Output Format (TOON)

The server supports TOON (Token-Oriented Object Notation) format for tool results, which can significantly reduce token usage (30-50%) when working with LLMs.

JSON output (default):

{"members":[{"person_id":1,"person_name":"Alice"},{"person_id":2,"person_name":"Bob"}],"total":2}

TOON output (compact):

members[2]{person_id,person_name}:
  1,Alice
  2,Bob
total: 2

To enable TOON format:

Via Environment Variable:

export FLASHDUTY_OUTPUT_FORMAT=toon

Via Command-line:

./flashduty-mcp-server stdio --output-format toon

Note: TOON format is particularly effective for arrays of objects with uniform fields (e.g., member lists, incident lists). Most modern LLMs can parse TOON format naturally.

4. i18n / Overriding Descriptions (Local-Only)

The feature to override tool descriptions is only available for local deployments. You can achieve this by creating a flashduty-mcp-server-config.json file or by setting environment variables.

Via JSON File:

Create flashduty-mcp-server-config.json in the same directory as the binary:

{
  "TOOL_CREATE_INCIDENT_DESCRIPTION": "an alternative description",
  "TOOL_LIST_TEAMS_DESCRIPTION": "List all teams in Flashduty account"
}

Via Environment Variables:

export FLASHDUTY_MCP_TOOL_CREATE_INCIDENT_DESCRIPTION="an alternative description"

5. Logging & Security

The server provides structured logging and built-in security features:

• Data Masking: Sensitive information such as APP_KEY and Authorization headers are automatically masked in logs to prevent accidental credential leakage.
• Log Truncation: Large request/response bodies are automatically truncated in logs (default 2KB) to maintain performance.
• W3C Trace Context: Supports W3C Trace Context (traceparent) for end-to-end observability. Trace IDs are automatically included in logs for easy request tracking.

Available Toolsets

The following toolsets are available (all are on by default). You can also use all to enable all toolsets.

Total: 16 tools

Tools

incidents - Incident Lifecycle Management (6 tools)

• query_incidents - Query incidents with enriched data (timeline, alerts, responders)
• create_incident - Create a new incident
• update_incident - Update incident (title, description, severity, custom_fields)
• ack_incident - Acknowledge incidents
• close_incident - Close (resolve) incidents
• list_similar_incidents - Find similar historical incidents

changes - Change Record Query (1 tool)

• query_changes - Query change records with filters

status_page - Status Page Management (4 tools)

• query_status_pages - Query status pages with full configuration
• list_status_changes - List change events on status page
• create_status_incident - Create incident on status page
• create_change_timeline - Add timeline update to status change

users - Member and Team Query (2 tools)

• query_members - Query members with optional filters
• query_teams - Query teams with member details

channels - Channels and Escalation Rules (2 tools)

• query_channels - Query channels with enriched data (team and creator names)
• query_escalation_rules - Query escalation rules for a channel

fields - Custom Field Definitions (1 tool)

• query_fields - Query custom field definitions

Library Usage

The exported Go API of this module should currently be considered unstable, and subject to breaking changes. In the future, we may offer stability; please file an issue if there is a use case where this would be valuable.

License

This project is licensed under the MIT License - see the LICENSE file for details.