SutramX

SutramX MCP 服务

一个 Model Context Protocol 服务，让 AI Agent 和助手（Claude Code、Claude Desktop 及其他 MCP 客户端）能够使用你的 SutramX 工作区：列出和更改监控项、读取检查结果、处理事件并管理状态页。

它使用工作区 API 密钥与公开的 SutramX API 通信，因此只能执行该密钥所允许的操作，除此之外别无权限。

工具

工具	功能	是否更改数据？
sutramx_whoami	此密钥对应的工作区、套餐和限额	否
sutramx_monitor_summary	按状态统计的数量、未解决事件、24 小时正常运行时间	否
sutramx_list_monitors	显示实时状态和正常运行时间的监控项；可按状态、标签和文本筛选	否
sutramx_get_monitor	按 ID 或 monitoring-as-code 键获取单个监控项	否
sutramx_create_monitor	创建任意类型的监控项：http、api、ping、port、udp、dns、multistep、mcp（远程 MCP 服务：initialize + tools/list、预期工具、工具列表变更）或 cron（传入 key 可幂等地创建或更新）	是
sutramx_update_monitor	更改名称、URL、间隔、配置、标签和区域	是
sutramx_pause_monitor / sutramx_resume_monitor	停止或重新启动检查（每小时暂停次数有上限，参见安全限制）	是
sutramx_delete_monitor	删除监控项及其历史记录（除非启用删除功能，否则隐藏）	是，有破坏性
sutramx_run_check	立即执行一次真实检查	会记录检查结果
sutramx_get_check_results	按区域和状态分页查看检查历史	否
sutramx_list_incidents / sutramx_get_incident	事件及其确认区域和确认状态	否
sutramx_explain_incident	“为什么宕机？”/“为什么触发了此警报？”：可按事件 ID、监控项 ID 或监控项名称/键查询，返回判定结果、责任方（你、外部服务或我们的检查器）、各区域的投票（被阻止和无法判定的区域弃权）、法定人数规则及是否满足、故障类别、供应商信号和 7/30 天波动评分；没有未解决事件的监控项会返回其当前状态和最近一次事件	否
sutramx_acknowledge_incident	确认事件（停止升级通知）	是
sutramx_resolve_incident	手动解决事件并添加备注	是
sutramx_add_incident_note	添加内部时间线备注（仅在破坏性模式下更新公开状态页）	是
sutramx_list_status_pages / sutramx_get_status_page	状态页及其上的监控项	否
sutramx_create_status_page / sutramx_update_status_page	创建状态页（除非启用破坏性模式，否则不会公开），或更改其 title、description、logo_url、accent_color、favicon_url、hide_powered_by、show_response_times；slug 和 is_public，以及对公开状态页的任何更改，仅能在破坏性模式下执行（任何其他设置都会被拒绝）	是
sutramx_set_status_page_monitors	替换状态页上显示的监控项（除非启用破坏性模式，否则隐藏；空列表需要设置 remove_all: true）	是，有破坏性
sutramx_delete_status_page	删除状态页（除非启用删除功能，否则隐藏）	是，有破坏性
sutramx_uptime_report	按监控项统计 7/14/30/90 天的正常运行时间百分比、事件、MTTR 和健康评分，以及 SLO 错误预算和消耗速率	否
sutramx_list_maintenance_windows	维护窗口（范围、计划、重复规则）；可按状态筛选	否
sutramx_list_regions	监控位置及其代码	否

破坏性工具带有 destructiveHint 注释，因此支持此功能的客户端会在运行前请求确认。读取工具带有 readOnlyHint 和 openWorldHint: false（它们只读取你的工作区）；会使 SutramX 联系外部目标、发布内容或通知他人的工具带有 openWorldHint: true。

访问模式

Agent 可以被其读取的文本引导（提示词注入），因此由用户而非 Agent 来选择服务提供哪些工具。未获允许的工具根本不会注册：Agent 永远看不到它们。

模式	stdio（环境变量）	HTTP（整个服务的环境变量，或每个客户端的请求头）	提供的工具
只读	SUTRAMX_READ_ONLY=true	X-SutramX-Read-Only: true	仅限上文标记为“no”的行
默认	（均未设置）	（均未设置）	除破坏性操作行以外的所有内容；不包括发布
破坏性模式	SUTRAMX_ALLOW_DESTRUCTIVE=true	仅环境变量；或者在操作员设置了 SUTRAMX_HTTP_ALLOW_DESTRUCTIVE_HEADER=true 时使用 X-SutramX-Allow-Destructive: true	所有内容

破坏性模式涵盖所有会删除数据或改变公众可见内容的操作：

• 只有在破坏性模式下才会注册删除工具和 sutramx_set_status_page_monitors（它可以将监控项从页面中移除）；
• sutramx_update_status_page 会拒绝修改 slug 和 is_public（发布、取消发布或移动页面），也会拒绝对公开页面进行任何更改（标题、徽标、颜色及其他内容都对所有人可见）；sutramx_create_status_page 创建的页面不会公开；在破坏性模式之外，sutramx_add_incident_note 会拒绝 public: true（状态页更新）。

注意：

• 两项设置默认均关闭。true、1、yes 和 on（不区分大小写）会开启设置；其他任何值都会使设置保持关闭。没有任何工具参数可以更改它们。
• 只读模式优先：开启只读模式后，即使处于破坏性模式，破坏性工具仍会隐藏。
• HTTP 模式：在服务端设置 SUTRAMX_READ_ONLY=true 后，无论请求头如何，所有请求都将只读；X-SutramX-Read-Only: true 会将只读限制应用于单个客户端。在服务端设置 SUTRAMX_ALLOW_DESTRUCTIVE=true 后，所有非只读请求都会启用破坏性模式。除非操作员同时设置了 SUTRAMX_HTTP_ALLOW_DESTRUCTIVE_HEADER=true，否则会忽略 X-SutramX-Allow-Destructive: true。
• 没有任何工具可以向任意收件人发送测试通知、电子邮件、短信或电话，也不能读取本地文件、运行命令或获取任意 URL。

安全限制

更改数据的工具按会话进行速率限制（stdio：进程；HTTP：API 密钥）：每分钟最多更改 SUTRAMX_MAX_WRITES_PER_MINUTE 次（默认值为 20），每小时最多更改 SUTRAMX_MAX_WRITES_PER_HOUR 次（默认值为 200）；在破坏性模式之外，每小时最多暂停监控项 SUTRAMX_MAX_PAUSES_PER_HOUR 次（默认值为 10）。超出限制时，工具会返回错误，提示 Agent 请用户介入；API 自身的每个密钥限制也会叠加生效。

• 对于只需查看信息的助手（如事件分诊、报告），请使用只读模式，最好同时使用只读 API 密钥（见下文）。

1. 创建 API 密钥

在 SutramX 中，打开 Settings → API keys → Create API key。密钥以 sk_ 开头，且只会显示一次。

推荐 Agent 使用只读密钥。 它可以调用上文所有标记为“no”的工具，而 SutramX API 本身会拒绝它尝试进行的任何更改（403 READ_ONLY_ACCESS），因此即使密钥泄露或 Agent 遭到提示词注入，也无法创建、暂停、确认、解决或删除任何内容。即使服务自身的只读模式已关闭，这项保护仍然有效；同时启用两者（SUTRAMX_READ_ONLY=true 也会对 Agent 隐藏写入工具）。只有确实需要更改内容的 Agent 才应使用标准密钥；标准密钥足以调用上文的所有工具。

2. 构建

cd mcp-server
npm install
npm run build

需要 Node.js 20 或更高版本。

3. 连接客户端

Claude Code

claude mcp add sutramx \
  --env SUTRAMX_API_KEY=sk_your_key \
  -- node /absolute/path/to/mcp-server/dist/index.js

或者将其添加到项目的 .mcp.json 中：

{
  "mcpServers": {
    "sutramx": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": { "SUTRAMX_API_KEY": "sk_your_key" }
    }
  }
}

Claude Desktop

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json，Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "sutramx": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": { "SUTRAMX_API_KEY": "sk_your_key" }
    }
  }
}

重启 Claude Desktop。试试提问：“SutramX 中目前有哪些监控项已宕机？从什么时候开始的？”

Streamable HTTP（远程或共享）

PORT=3333 node dist/index.js --http

端点为 POST http://127.0.0.1:3333/mcp（无状态，返回 JSON）。每个请求都必须携带各自的 SutramX 密钥：

Authorization: Bearer sk_your_key

这样一台服务就能为多个用户和工作区提供服务。每个密钥只能访问自己的工作区。使用以下命令将 Claude Code 连接到它：

claude mcp add --transport http sutramx http://127.0.0.1:3333/mcp \
  --header "Authorization: Bearer sk_your_key"

当服务监听 loopback 地址（默认值为 HOST=127.0.0.1）时，对于未发送 Authorization 标头的请求，会使用 SUTRAMX_API_KEY（如果标头不是 SutramX 密钥，则会被拒绝并返回 401）。除非请求来源已列入 MCP_ALLOWED_ORIGINS，否则会拒绝浏览器请求（包括来自 localhost 页面、带有 Origin 标头的任何请求），以防本地开发服务或其他 localhost Web 应用使用你的密钥。若要使用基于浏览器的客户端（例如 MCP Inspector），请列出其来源，例如 MCP_ALLOWED_ORIGINS=http://localhost:6274。环境密钥仅会提供给不带 Origin 的请求，或来源名称在列表中的请求（* 条目允许发送自身密钥的浏览器使用服务，但绝不会提供环境密钥）。若使用其他 HOST，则会忽略环境密钥，并且你应将服务置于 HTTPS 后方。设置 MCP_ALLOWED_HOSTS（以逗号分隔的主机名）可在绑定到 0.0.0.0 时保留 DNS 重绑定防护。GET /health 会返回服务版本。

使用 OAuth 的托管服务（Claude.ai 和其他远程客户端）

托管服务 https://api.sutramx.com/mcp 也支持 OAuth 2.1，因此无法存储 API 密钥的客户端（例如 Claude.ai 自定义连接器）只需提供 URL。首次发送不带凭据的请求时，服务会返回 401，并附带 WWW-Authenticate: Bearer resource_metadata="https://api.sutramx.com/.well-known/oauth-protected-resource/mcp"；客户端会自行注册（动态客户端注册），引导你前往 SutramX 批准授权，然后获取访问令牌（PKCE S256，资源标识符为 https://api.sutramx.com/mcp）。

在授权页面中，你可以选择工作区和权限：monitors:read、incidents:read、status_pages:read（默认启用），以及 monitors:write、incidents:write、status_pages:write（默认关闭，除非你勾选；工作区查看者只能授予读取权限）。没有写入范围的令牌只能使用读取工具。托管服务会禁用破坏性工具（删除、发布、修改 slug、替换状态页的监视器）；只有服务运营者才能启用这些工具（SUTRAMX_ALLOW_DESTRUCTIVE）。OAuth 令牌永远不能管理 API 密钥、团队成员、账单、SSO 或账户设置。访问令牌有效期为一小时，并会自动刷新；可随时在 SutramX → Settings → Authorized apps 中撤销应用授权。

使用 OAuth 自托管 HTTP 服务：将 MCP_RESOURCE_URL 设置为 /mcp 端点的公共 URL，并将 MCP_AUTHORIZATION_SERVER 设置为 SutramX API，然后由此服务提供 /.well-known/oauth-protected-resource*。设置 OAUTH_RESOURCE_PROXY_SECRET（至少 16 个字符，并使用 API 所需的值），使 OAuth 令牌能携带资源证明传递到 API。在 NODE_ENV=production（Docker 镜像的默认值）下，如果缺少该密钥或其长度少于 16 个字符，HTTP 服务会拒绝启动，而不会在未携带该密钥的情况下悄悄发送令牌。只接受 API 密钥的服务应设置 MCP_OAUTH=off：不会提供受保护资源元数据，并且会拒绝 OAuth 访问令牌。此设置不影响 stdio 模式。

配置

变量	默认值	用途
SUTRAMX_API_KEY	（stdio 必填）	工作区 API 密钥
SUTRAMX_API_URL	https://api.sutramx.com	API 基础 URL（可自托管或用于预发布环境）；仅由操作员设置，绝不从请求或工具参数中获取
TRANSPORT	stdio	http 与 --http 相同
HOST / PORT	127.0.0.1 / 3333	HTTP 监听器
MCP_ALLOWED_HOSTS	（无）	非环回地址时允许的 Host 标头
SUTRAMX_READ_ONLY	false	仅注册读取工具
SUTRAMX_ALLOW_DESTRUCTIVE	false	破坏性模式：删除工具、替换状态页监控项、发布与 slug 更改、编辑公开状态页、更新公开事件
SUTRAMX_HTTP_ALLOW_DESTRUCTIVE_HEADER	false	HTTP：允许客户端通过 X-SutramX-Allow-Destructive: true 选择启用破坏性模式
SUTRAMX_MAX_WRITES_PER_MINUTE / SUTRAMX_MAX_WRITES_PER_HOUR / SUTRAMX_MAX_PAUSES_PER_HOUR	20 / 200 / 10	每个会话的更改次数限制（参见安全限制）
MCP_RESOURCE_URL	<SUTRAMX_API_URL>/mcp	HTTP + OAuth：此 /mcp 端点的规范 URL（令牌受众）
MCP_AUTHORIZATION_SERVER	SUTRAMX_API_URL	HTTP + OAuth：受保护资源元数据中指定的发行方
OAUTH_RESOURCE_PROXY_SECRET	（无）	HTTP + OAuth：随 OAuth 令牌发送给 API 的资源证明（至少 16 个字符）；当 NODE_ENV=production 时必填，除非 MCP_OAUTH=off
MCP_OAUTH	on	HTTP：off 时仅接受 SutramX API 密钥（不提供 OAuth 元数据，并拒绝 OAuth 令牌）
SUTRAMX_API_INTERNAL_URL	（无）	HTTP：将 API 调用发送至此处，而非 SUTRAMX_API_URL（例如，与 API 相邻运行时使用 http://api:3003）；OAuth 元数据中的 SUTRAMX_API_URL 仍为公开 URL。纯 http:// 仅适用于环回地址、私有地址和单标签容器名称
TRUST_PROXY_HOPS	0	HTTP：服务器前方设置 X-Forwarded-For 的反向代理数量；仅设置此项后才会从中获取客户端地址（位于一个代理后时设为 1）
MCP_FAILED_AUTH_PER_IP	50	HTTP：15 分钟内每个客户端地址允许的凭据验证失败次数，超过后返回带有 Retry-After 的 429
MCP_ALLOWED_ORIGINS	（无）	允许调用 /mcp 的浏览器来源（以逗号分隔，例如 http://localhost:6274,https://app.example.com）；默认不允许任何浏览器来源，包括环回地址；始终允许不带 Origin 的请求
HTTPS_PROXY / HTTP_PROXY / NO_PROXY（或小写形式）	（无）	通过代理发送 API 调用；NO_PROXY 中的主机（例如 SUTRAMX_API_INTERNAL_URL 主机）将直接连接。位于 TLS 检查代理后方时，将 NODE_EXTRA_CA_CERTS 指向其 CA 证书

说明

• 套餐限制与控制面板中的设置完全一致。如果工具返回的错误包含 category: PLAN_LIMIT，或属于 ENTITLEMENT_LIMIT_REACHED、ENTITLEMENT_INTERVAL_TOO_SHORT、MONITOR_TOTAL_LIMIT_REACHED、CONNECTION_LIMIT_REACHED、LIMIT_REACHED、AI_LIMIT_REACHED 或 FEATURE_NOT_AVAILABLE，则表示套餐不允许执行该操作，并会告知 Agent 不要重试。
• API 调用：每个 POST 都会携带一个 Idempotency-Key。读取操作（包括只读的监控项 plan）、PUT、DELETE，以及每个键只创建一次 API 运行的 POST（监控项、状态页、事件说明等），在发生网络错误、超时（30 秒）、HTTP 502/503/504 或 429 时，会使用相同的键重试一次（遵循 Retry-After，无论其值是秒数还是日期，最多等待 5 秒；更长的等待时间会返回给 Agent）。其他 POST（确认、解决、暂停、恢复、运行检查）仅在遇到 429 时重试（API 在运行操作前已拒绝请求）；发生网络错误、超时或 5xx 时只发送一次，并将错误返回给 Agent，因为重试可能导致操作执行两次。网络故障会指出原因和主机（ECONNREFUSED、ENOTFOUND、ETIMEDOUT、CERT_* 等）；非 JSON 响应也会被视为错误。调用会携带 User-Agent 和 X-SutramX-Client: sutramx-mcp-server/<version>。
• 无法使用 API 密钥管理账单、团队成员和 API 密钥，因此也无法通过此服务进行管理。每个监控项的告警接收人（config.notification_emails）只能使用具有 Automation 访问权限的 API 密钥进行设置；其他密钥会收到明确的错误。
• 可以列出维护时段，但不能创建、修改或删除：维护时段会静默告警，因此 API 将其设为仅所有者可操作，并拒绝所有 API 密钥（403 WORKSPACE_OWNER_REQUIRED）。SLO 目标在控制面板中设置；sutramx_uptime_report 会读取这些目标。
• 使用只读密钥时，sutramx_whoami 会返回 read_only: true，任何写入工具都会返回 READ_ONLY_ACCESS，并提示 Agent 不要重试。
• sutramx_explain_incident 必须且只能接收 incident_id、monitor_id 或 monitor（名称、密钥或 URL 片段）其中之一。如果有多个监控项与名称匹配，则会返回 outcome: "ambiguous"，并提供最多 10 个候选项，同时告知 Agent 应询问用户，绝不能自行选择。其他结果包括：ongoing、resolved、healthy、failing_unconfirmed、no_data 和 paused；维护时段静默告警期间会设置 in_maintenance，而 incidents_total: 0 表示该监控项从未发生过事件。所有套餐均可使用事件说明。供应商信号仅以保护隐私的区间（several / many）提供受影响的 SutramX 账户数量。OAuth 连接需要 incidents:read（事件说明）和 monitors:read（监控状态和不稳定情况）。
• sutramx_update_monitor 中的 config 会替换整个对象。Agent 会收到指示：先读取监控项，再发送合并后的配置。

安全

• SUTRAMX_API_URL 必须使用 https://（仅环回地址可使用普通 http://）；否则服务器会拒绝启动。若设置了 NODE_TLS_REJECT_UNAUTHORIZED=0，服务器会发出警告；携带密钥时绝不跟随重定向。
• 在 HTTP 模式下，凭据验证失败（格式错误的 Authorization 标头，或 API 拒绝的 OAuth 令牌或 API 密钥）会按客户端地址进行限制（MCP_FAILED_AUTH_PER_IP），并且会在任何令牌发送到 API 之前检查；环回地址和私有地址不受限制（在代理后方时设置 TRUST_PROXY_HOPS）。设置 OAUTH_RESOURCE_PROXY_SECRET 后，API 调用会在 X-SutramX-Client-Ip 中携带客户端地址及其在该密钥下的 HMAC，使 API 能按每位用户的地址分别实施限制，而不是按服务器地址限制。
• 监控配置中存储的凭据（如 Authorization/Cookie 等标头、名称类似 *token*、*secret*、*password*、*api_key* 的密钥，以及 URL 中的密码）都会以 [REDACTED] 返回。将 [REDACTED] 发送回 sutramx_update_monitor 会保留已存储的值；若该值未存储，则不能用它代替。
• 来自受监控网站或其他人员的文本（检查错误、名称、备注）会显示在 «» 中，且仅占一行、不含控制字符；服务器指令会告知 Agent 将其视为数据。
• structuredContent（与文本并列的 JSON）会经过清理（移除控制字符、零宽字符和双向覆盖字符）；超过 8,000 个字符的字符串末尾会添加 [TRUNCATED]；整个结果上限为 25,000 个字符（丢弃项目时，"truncated": true）。发送回以 [TRUNCATED] 结尾的值会被拒绝。若干列表工具声明了 outputSchema。
• sutramx_list_monitors 最多扫描 5,000 个监控项和 5 MB 的响应（API 只按标签筛选）；读取 API 响应时，每个响应的上限为 10 MB。
• ID 必须是 UUID，密钥和 slug 必须符合严格模式，时间必须采用 ISO-8601 格式，因此工具参数无法更改 API 路径或添加查询参数。
• HTTP 模式：每个请求都需要各自的 Authorization: Bearer sk_...；环境变量中的密钥仅在环回地址上作为后备。面向公众部署时，请在前方设置速率限制器（API 本身会按密钥限速）。

开发

npm run dev          # stdio, from source
npm test             # tool tests against a fake API
npx @modelcontextprotocol/inspector node dist/index.js   # interactive inspector

许可证

MIT，详见 LICENSE。