> ## Documentation Index > Fetch the complete documentation index at: https://docs.flashduty.com/llms.txt > Use this file to discover all available pages before exploring further. # MCP Server > 通过 MCP 协议将 Flashduty API 接入 AI 工具，在 Cursor、Claude 等客户端中实现智能化故障管理与自动化。 Flashduty MCP Server 是一个 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 服务端，将 Flashduty API 接入支持 MCP 的 AI 工具（如 Cursor、Claude Desktop）。借助它，您可以让大模型直接查询故障、确认与关闭故障、检索协作空间与成员、校验通知模板，把故障管理与自动化能力嵌入 AI 工作流。 Flashduty MCP Server 提供的是经过整理的任务型工具集，并不完整镜像 Flashduty 开放 API。需要 1:1 覆盖全部开放 API 时，请使用 [Flashduty CLI](/zh/developer/cli)；具备 shell 权限的 Agent 也可以直接调用 CLI。 ## 适用场景 将 Flashduty 的故障创建、确认、关闭等操作交给 AI 编排，串联到您的运维工作流中。 让大模型按时间范围、状态、严重程度等条件检索故障、告警与变更记录并归纳分析。 在自研 AI 应用中调用 Flashduty 能力，构建智能值守、故障复盘等场景。 在编辑通知模板时，实时校验渲染结果、查询可用变量与函数。 ## 部署方式 Flashduty MCP Server 提供三种部署方式，您可以根据 MCP 客户端的能力与运行环境选择。 无需本地安装，直接连接官方远程实例 `https://mcp.flashcat.cloud/mcp`，这是最快的接入方式。远程服务支持两种认证方式，按客户端能力二选一： * **OAuth 登录**：客户端支持 MCP OAuth（如 claude.ai、Claude Desktop、ChatGPT connectors）时，新建一个自定义连接器，地址填 `https://mcp.flashcat.cloud/mcp`，不要填写任何凭据。客户端会自动发现 Flashduty 授权服务器并在浏览器打开授权页，您完成授权后即以自己的身份调用 Flashduty 开放 API，权限与 APP Key 相同。 * **APP Key**：客户端不支持 OAuth 时，改用 `Authorization: Bearer` 请求头携带您的 APP Key。 OAuth 登录只需要一个地址： ```json theme={null} { "mcpServers": { "flashduty": { "url": "https://mcp.flashcat.cloud/mcp" } } } ``` 使用 APP Key 时，以 Cursor 为例，在 MCP 配置中添加： ```json theme={null} { "mcpServers": { "flashduty": { "url": "https://mcp.flashcat.cloud/mcp", "headers": { "Authorization": "Bearer " } } } } ``` 远程服务仅支持 Streamable HTTP 传输（`POST /mcp`）。请参考您所用 MCP 客户端的文档，确认远程 MCP 服务的配置语法与位置。 在本地通过 Docker 运行，使用 `FLASHDUTY_APP_KEY` 环境变量认证，采用 stdio 传输。 ```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" } } } } ``` 从 [GitHub Releases](https://github.com/flashcatcloud/flashduty-mcp-server/releases) 下载预编译版本，或在 `cmd/flashduty-mcp-server` 目录下用 `go build` 自行构建。APP Key 既可通过环境变量传入，也可通过命令行参数传入。 **通过环境变量：** ```json theme={null} { "mcpServers": { "flashduty": { "command": "/path/to/flashduty-mcp-server", "args": ["stdio"], "env": { "FLASHDUTY_APP_KEY": "your_app_key_here" } } } } ``` **通过命令行参数：** ```json theme={null} { "mcpServers": { "flashduty": { "command": "/path/to/flashduty-mcp-server", "args": ["stdio", "--app-key", "your_app_key_here"] } } } ``` ## 认证与传输 | 项目 | 说明 | | - | - | | 认证（本地） | 通过 `FLASHDUTY_APP_KEY` 环境变量或 `--app-key` 命令行参数提供 Flashduty APP Key。 | | 认证（远程，OAuth） | 支持 MCP OAuth 的客户端无需提供凭据，在浏览器完成 Flashduty 授权即可。OAuth 只适用于远程服务，没有对应的环境变量或命令行参数。 | | 认证（远程，APP Key） | 通过请求头 `Authorization: Bearer ` 提供 APP Key。 | | Streamable HTTP | `flashduty-mcp-server http`，端点为 `POST /mcp`。官方远程实例为 `https://mcp.flashcat.cloud/mcp`。 | | stdio | `flashduty-mcp-server stdio`，用于 Cursor、Claude Desktop 等本地客户端。 | 服务端不支持旧版独立 SSE 传输（单独的 `GET /sse` 端点），对 `GET` 请求会返回 `405 Method Not Allowed`。Streamable HTTP 已按 MCP 规范在 `POST` 上完成流式响应，请直接使用它；若客户端仅支持旧版 SSE，请升级客户端或在本地改用 stdio。 ### OAuth 授权与发现 远程服务同时接受 MCP OAuth 访问令牌与 APP Key：凭据以 `oauth:` 开头时按访问令牌处理，其余 Bearer 凭据一律按 APP Key 处理，两者权限相同。 未携带任何凭据的请求会返回 `401`，并在 `WWW-Authenticate` 响应头中给出受保护资源元数据地址 `Bearer resource_metadata="<请求源>/.well-known/oauth-protected-resource"`。客户端据此发现元数据、进而发起 OAuth 授权流程。服务端提供以下元数据地址： | 元数据地址 | 说明 | | - | - | | `/.well-known/oauth-protected-resource` | 根路径，描述 `/mcp`。 | | `/.well-known/oauth-protected-resource/mcp` | 描述 `/mcp`。 | | `/.well-known/oauth-protected-resource/flashduty` | 描述兼容保留的 `/flashduty` 路径。 | 元数据中的 `resource` 是请求源加上对应路径，`authorization_servers` 是 Flashduty API 地址，即本地通过 `FLASHDUTY_BASE_URL` 或 `--base-url` 配置的地址（默认 `https://api.flashcat.cloud`）——该地址同时充当授权服务器。访问令牌只在签发它的那个 API 地址上有效，因此远程 URL 上的 `base_url` 对 OAuth 令牌不生效，对 APP Key 仍然生效。 ## 配置项 Flashduty MCP Server 支持工具集裁剪、只读模式、输出格式等配置，以适配不同使用场景。本地部署可通过环境变量或命令行参数配置；远程服务可通过在 URL 上追加查询参数动态配置。 ### 环境变量
字段默认值说明
`FLASHDUTY_APP_KEY`-Flashduty APP Key（必填）。
`FLASHDUTY_TOOLSETS`全部工具集以逗号分隔，指定启用的工具集（如 `incidents,users,channels`）；可用 `all` 启用全部。
`FLASHDUTY_READ_ONLY``false`开启只读模式（`1` 或 `true`），仅保留查询类工具，禁止任何写操作。
`FLASHDUTY_OUTPUT_FORMAT``json`工具结果输出格式，可选 `json` 或 `toon`。
`FLASHDUTY_BASE_URL``https://api.flashcat.cloud`Flashduty API 的基础地址。
仅启用您需要的工具集，既能帮助大模型更准确地选择工具，也能减小上下文体积。开启只读模式可在数据分析、值守巡检等只需读取的场景下提升安全性。 **Docker 示例：** ```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 ``` ### 命令行参数 从源码构建并直接运行二进制时，可使用以下命令行参数（优先级高于同名环境变量）： ```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（等价于 `FLASHDUTY_APP_KEY`）。 * `--toolsets`：以逗号分隔的启用工具集列表。 * `--read-only`：开启只读模式。 * `--output-format`：工具结果输出格式（`json` 或 `toon`）。 * `--base-url`：Flashduty API 基础地址。 ### 远程服务配置 使用官方远程实例时，可在 URL 上追加查询参数动态配置工具集、只读模式与 Flashduty API 地址： ```json theme={null} { "mcpServers": { "flashduty": { "url": "https://mcp.flashcat.cloud/mcp?toolsets=incidents,users&read_only=true", "headers": { "Authorization": "Bearer " } } } } ``` | 查询参数 | 说明 | | - | - | | `toolsets` | 以逗号分隔的启用工具集列表（如 `incidents,users,channels`）。 | | `read_only` | 设为 `true` 开启只读模式。 | | `base_url` | 覆盖 Flashduty API 地址，只对 APP Key 请求生效；OAuth 访问令牌只在签发它的 API 地址上有效，会忽略该参数。 | ### 输出格式（TOON） 服务端支持 [TOON（Token-Oriented Object Notation）](https://github.com/toon-format/toon)格式输出工具结果。对于字段统一的对象数组（如成员列表、故障列表），TOON 相比 JSON 可显著减少 30%-50% 的 Token 消耗，且现代大模型可直接解析。设置 `FLASHDUTY_OUTPUT_FORMAT=toon`（或 `--output-format toon`）即可启用。 ## 工具集与工具 服务端共提供 **8 个工具集、23 个工具**，默认全部启用。下表为各工具集概览： | 工具集 | 工具数 | 说明 | | - | - | - | | `incidents` | 8 | 故障全生命周期管理与查询 | | `status_page` | 4 | 状态页（Status Page）管理 | | `templates` | 4 | 通知模板校验与变量、函数查询 | | `users` | 2 | 成员与团队查询 | | `channels` | 2 | 协作空间与升级规则查询 | | `alerts` | 1 | 告警原始事件查询 | | `changes` | 1 | 变更记录查询 | | `fields` | 1 | 自定义字段定义查询 | 工具集名称（`incidents`、`status_page` 等）为程序内部标识，配置时请保持英文原样。 ### 分页参数 列表型查询工具使用统一分页规则：`limit` 表示每页数量，默认 `20`，最大 `100`；`page` 表示从 `1` 开始的页码，默认 `1`。当返回结果还没有取完时，响应会包含 `truncated: true` 和 `hint`，其中会明确提示下一次请求应传入的页码，例如 `page:2`。 支持 `limit` / `page` 的工具包括： | 工具 | 分页行为 | | - | - | | `query_incidents` | 普通列表查询按 `limit` / `page` 翻页；使用 `incident_ids` 直接查找时忽略其他过滤条件，不走分页 | | `query_incident_alerts` | `page` 会应用到每个指定故障的告警列表；某个故障仍有更多告警时，该故障结果内会带 `truncated` 与 `hint` | | `query_channels` | 名称搜索和 `channel_ids` 过滤都走同一个分页列表接口，因此都支持 `limit` / `page` | | `query_members` | 按名称或邮箱搜索时支持分页；使用 `person_ids` 直接查找时返回指定成员，不走分页 | | `query_teams` | 按名称搜索时支持分页；使用 `team_ids` 直接查找时返回指定团队，不走分页 | | `query_changes` | 普通过滤查询支持分页；使用 `change_ids` 时会在当前页内做客户端过滤，并返回匹配数量，不追加分页提示 | 各工具集包含的工具如下： | 工具 | 说明 | | - | - | | `query_incidents` | 按 ID、短号、时间范围、状态、严重程度、协作空间或自由文本查询故障，返回故障列表及每条故障的告警总数。 | | `query_incident_timeline` | 查询故障的时间线事件（创建、分派、确认、解决、通知等）。每条事件包含 `created_at`（RFC3339 格式）和 `creator_id`（操作者数字 ID，0 表示系统自动操作）；如需将 `creator_id` 转换为显示名称，可调用 `query_members`。 | | `query_incident_alerts` | 查询故障关联的告警，返回标题、严重程度、状态与标签。 | | `create_incident` | 创建故障，指定标题与严重程度，可选分派到协作空间或响应人。 | | `update_incident` | 更新故障的内置字段（标题、描述、严重程度、影响、根因、解决方案）及自定义字段，仅更新提供的字段。 | | `ack_incident` | 确认故障，将状态从「已触发」转为「处理中」。 | | `close_incident` | 关闭（解决）故障，将状态转为「已关闭」。 | | `list_similar_incidents` | 查找历史相似故障，用于复盘既往处置方案、识别重复问题。 | **`query_incidents` 参数说明** | 参数 | 类型 | 说明 | | - | - | - | | `incident_ids` | string | 逗号分隔的完整故障 ID，用于直接查找。提供此参数时其他过滤条件将被忽略。 | | `nums` | string | 逗号分隔的短号（6 位数字，即 UI 中显示的短 ID，如 `311510`）。短号匹配在 `since`/`until` 时间窗口内进行，后端单次查询上限约 30 天；超过 30 天的历史故障需改用完整 `incident_id` 查询。 | | `since` | string | 查询起始时间（见下方时间格式说明）。 | | `until` | string | 查询截止时间（见下方时间格式说明）。 | | `progress` | string | 按状态过滤，可选：`Triggered`、`Processing`、`Closed`，逗号分隔支持多选。 | | `severity` | string | 按严重程度过滤，可选：`Info`、`Warning`、`Critical`。 | | `channel_ids` | string | 逗号分隔的协作空间 ID。 | | `query` | string | 自由文本搜索（标题、标签、内容）。 | | `limit` | number | 每页返回数量，默认 20，最大 100。 | | `page` | number | 页码，从 1 开始；当响应包含 `truncated: true` 时，按 `hint` 提示请求下一页。 | **`since` / `until` 时间窗口行为** * **两者均省略**：默认查询最近 30 天（适合查询当前未关闭故障）。 * **仅提供 `since`**：从该时间查询到当前时刻。 * **仅提供 `until`**：不允许，返回错误（`since` 为必填，或两者都省略）。 * **同时提供**：查询指定时间段，后端硬上限约 30 天。 **时间格式**：支持以下任意格式： * 相对时长：`30d`、`24h`、`168h`（表示距今多久之前） * RFC3339 含时区：`2026-04-01T10:00:00+08:00` 或 `2026-04-01T10:00:00Z`（SDK 返回的时间戳可直接用作过滤参数） * 日期：`2026-04-01`（解析为本地时间零点） * 日期时间：`2026-04-01 10:00:00` 或 `2026-04-01T10:00:00`（本地时间） * Unix 时间戳：`1712000000` | 工具 | 说明 | | - | - | | `query_status_pages` | 查询状态页及其完整配置。 | | `list_status_changes` | 列出状态页上当前进行中（未关闭）的变更事件（故障或维护）。仅返回活跃事件，已解决或已完成的历史事件不在返回范围内。 | | `create_status_incident` | 在状态页上创建事件。 | | `create_change_timeline` | 为状态页变更追加时间线更新。 | | 工具 | 说明 | | - | - | | `get_preset_template` | 获取指定协作空间的预置（默认）通知模板，返回可作为定制起点的 Go 模板代码。 | | `validate_template` | 校验通知模板：解析并以故障数据渲染，返回渲染预览、校验状态与大小信息，支持 mock 数据或基于 `incident_id` 的真实预览。 | | `list_template_variables` | 列出通知模板中可用的所有变量，返回带类型、说明与示例值的变量结构。 | | `list_template_functions` | 列出通知模板中可用的所有函数，含 Flashduty 自定义函数与常用 Sprig 函数。 | | 工具 | 说明 | | - | - | | `query_members` | 查询成员，支持可选过滤条件。 | | `query_teams` | 查询团队及其成员详情。 | | 工具 | 说明 | | - | - | | `query_channels` | 查询协作空间，返回团队、创建者等增强数据。 | | `query_escalation_rules` | 查询某个协作空间的升级规则。 | | 工具 | 说明 | | - | - | | `query_alert_events` | 查询单条告警的原始事件，返回产生该告警的上游事件流（如每次 Prometheus 触发）。 | | 工具 | 说明 | | - | - | | `query_changes` | 按过滤条件查询变更记录。 | | 工具 | 说明 | | - | - | | `query_fields` | 查询自定义字段定义。 | ## 相关资源 MCP Server 底层依赖的 Go SDK，覆盖 Flashduty 全部开放 API。 覆盖 Flashduty 开放 API 的命令行工具，适合需要完整 API 能力的 Agent。 查看源码、Release 与问题反馈。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.