# Flashduty Mcp Server

> Flashduty's official MCP Server

- **Type:** MCP server
- **Install:** `agentstack add mcp-flashcatcloud-flashduty-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [flashcatcloud](https://agentstack.voostack.com/s/flashcatcloud)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [flashcatcloud](https://github.com/flashcatcloud)
- **Source:** https://github.com/flashcatcloud/flashduty-mcp-server

## Install

```sh
agentstack add mcp-flashcatcloud-flashduty-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Flashduty MCP Server

English | [中文](README_zh.md)

The Flashduty MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that provides seamless integration with Flashduty APIs, enabling advanced incident management and automation capabilities for developers and tools.

### 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

| Transport | Supported | Notes |
|---|---|---|
| **stdio** | ✅ | `flashduty-mcp-server stdio`. Use this for local hosts (Cursor, Claude Desktop, etc.). |
| **Streamable HTTP** | ✅ | `flashduty-mcp-server http`. Endpoints: `/mcp` (canonical) and `/flashduty` (legacy alias). Public instance: `https://mcp.flashcat.cloud/mcp`. |
| **Standalone SSE (HTTP/SSE)** | ❌ | The legacy SSE transport (separate `GET /sse` endpoint) is **not supported**. The server returns `405 Method Not Allowed` for `GET` requests by design. Use Streamable HTTP — it already streams responses over `POST` per the MCP spec. |

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

---

## Remote Flashduty MCP Server

[](#remote-cursor)

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](#local-flashduty-mcp-server) instead.

### Prerequisites

1. An MCP host that supports the latest MCP specification and remote servers, such as [Cursor](https://www.cursor.com/).
2. A Flashduty APP key from your Flashduty account.

### Installation

#### For example, with Cursor:

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

```json
{
  "mcpServers": {
    "flashduty": {
      "url": "https://mcp.flashcat.cloud/mcp",
      "headers": {
        "Authorization": "Bearer "
      }
    }
  }
}
```

> **Note:** Refer to your MCP host's documentation for the correct syntax and location for remote MCP server setup.

---

## Local Flashduty MCP Server

[](#local-cursor)

### Prerequisites

1. To run the server in a container, you will need to have [Docker](https://www.docker.com/) 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.

```json
{
  "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](https://github.com/flashcatcloud/flashduty-mcp-server/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:**
```json
{
  "mcpServers": {
    "flashduty": {
      "command": "/path/to/flashduty-mcp-server",
      "args": ["stdio"],
      "env": {
        "FLASHDUTY_APP_KEY": "your_app_key_here"
      }
    }
  }
}
```

**Via Command-line Argument:**
```json
{
  "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:

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

- `headers.Authorization`: Your Flashduty APP key for authentication, prefixed with `Bearer `.
- `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.

| Variable | Description | Required | Default |
|---|---|---|---|
| `FLASHDUTY_APP_KEY` | Flashduty APP key | ✅ | - |
| `FLASHDUTY_TOOLSETS` | Toolsets to enable (comma-separated) | ❌ | All toolsets |
| `FLASHDUTY_READ_ONLY` | Restrict to read-only operations (`1` or `true`) | ❌ | `false` |
| `FLASHDUTY_OUTPUT_FORMAT` | Output format for tool results (`json` or `toon`) | ❌ | `json` |
| `FLASHDUTY_BASE_URL` | Flashduty API base URL | ❌ | `https://api.flashcat.cloud` |
| `FLASHDUTY_LOG_FILE` | Log file path | ❌ | stderr |
| `FLASHDUTY_ENABLE_COMMAND_LOGGING` | Enable command logging | ❌ | `false` |
| `TZ` | Timezone for log timestamps (e.g., `Asia/Shanghai`, `America/New_York`) | ❌ | System default (falls back to `Asia/Shanghai` in containers without timezone data) |

**Docker Example:**

```bash
docker run -i --rm \
  -e FLASHDUTY_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.

```bash
./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)](https://github.com/toon-format/toon) format for tool results, which can significantly reduce token usage (30-50%) when working with LLMs.

**JSON output** (default):
```json
{"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:**
```bash
export FLASHDUTY_OUTPUT_FORMAT=toon
```

**Via Command-line:**
```bash
./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:
```json
{
  "TOOL_CREATE_INCIDENT_DESCRIPTION": "an alternative description",
  "TOOL_LIST_TEAMS_DESCRIPTION": "List all teams in Flashduty account"
}
```

**Via Environment Variables:**

```sh
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.

| Toolset        | Description                                      | Tools |
| -------------- | ------------------------------------------------ | ----- |
| `incidents`    | Incident lifecycle management                    | 6     |
| `changes`      | Change record query                              | 1     |
| `status_page`  | Status page management                           | 4     |
| `users`        | Member and team query                            | 2     |
| `channels`     | Channels and escalation rules                    | 2     |
| `fields`       | Custom field definitions                         | 1     |

**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](LICENSE) file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [flashcatcloud](https://github.com/flashcatcloud)
- **Source:** [flashcatcloud/flashduty-mcp-server](https://github.com/flashcatcloud/flashduty-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-flashcatcloud-flashduty-mcp-server
- Seller: https://agentstack.voostack.com/s/flashcatcloud
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.