将 MCP 客户端连接到 你的屏幕

服务器

服务器不保留会话。拒绝 GET、DELETE、Mcp-Session-Id 和 Cookie。每个请求独立认证，断开连接的应用在下一次调用时停止工作。请求大小限制为 4 MiB。

官方插件涵盖完整工作流程：它在你的机器上上传文件并打包应用。当客户端通过 MCP 调用工具时使用 MCP 服务器，并保留捆绑的 CLI 用于本地工作。

使用 OAuth 连接

MCP 客户端自行查找登录。无令牌的请求以 401 响应 WWW-Authenticate: Bearer resource_metadata="https://api.screenrig.ai/.well-known/oauth-protected-resource/mcp"，该文档命名授权服务器 https://api.screenrig.ai。其元数据位于 https://api.screenrig.ai/.well-known/oauth-authorization-server。

1. 将服务器 URL 添加到客户端。客户端将在浏览器中打开 screenRIG 同意页面。
2. 如有需要，登录控制台。页面显示应用名称和域名，按应用声明的方式，无论是否由 screenRIG 注册，以及浏览器返回的位置。
3. 选择项目、只读、提议或管理权限及功能，然后选择连接应用并使用您的通行密钥确认。
4. 你的浏览器返回应用，应用拥有自己的会话。它会自行续期；每个访问令牌有效 15 分钟。

仅连接你当前正在设置的应用。客户端通过客户端 ID 元数据文档（CIMD）进行识别，无需注册步骤。授权使用 PKCE，配合 S256、精确重定向 URI 和有效期 60 秒的一次性代码。

应用显示在仪表板 访问 页的 已连接应用 下。断开连接 可在几秒内结束连接；重新连接可选择不同项目或访问级别。详见 认证 了解其背后的会话。

CLI 和 MCP 主机保持独立会话。请勿将 CLI 保存的令牌复制到 MCP 配置，或将凭据粘贴到对话中，或传递给嵌入卡。主机自行管理 OAuth 令牌和刷新。

官方插件请求access:manage、screens、content、playlists和reports；用户在登录时批准访问。新截图需要 Propose 或 Manage 访问权限和screens能力。现有的只读连接在请求截图前需要重新同意。

MCP 应用主机可通过认证连接渲染交互式屏幕、媒体和播放列表卡片。卡片使用主机的 MCP 应用桥；不包含凭证且不直接调用 API。无 MCP 应用渲染的主机仍可使用工具文本和结构化数据。

只读、提议和管理

已连接的应用默认设置为只读。只读应用仅列出读取工具，调用超出会话级别的工具时，返回 HTTP 403 insufficient_access，带有 WWW-Authenticate: Bearer error="insufficient_scope" 和允许访问的 scope。Webhook 接收器 URL 对只读权限显示为已编辑。

Propose 应用还列出上传、注释和提议的工具。其播放列表和屏幕更改返回 status: "pending_review"，带审核的 id 和 url，而非直接应用，由人员在控制台的 审核 中批准。当项目要求代理更改审核时，所有应用最多只能在 Propose 工作。要让应用直接更改，断开连接后用 Manage 重新连接。

tools/list 仅返回会话访问级别和能力允许的工具。项目计划权限同样适用，和 CLI 一样。每个工具调用都是代理请求，计费如同其他请求。

连接 Claude

在 Claude（网页、桌面或移动端）中，添加一个自定义连接器，URL 为 https://api.screenrig.ai/mcp，然后连接。Claude 会打开同意页面。

在 Claude Code 中，添加服务器，然后从 /mcp 认证：

claude mcp add --transport http screenrig https://api.screenrig.ai/mcp

连接 ChatGPT

在 ChatGPT 中，使用服务器 URL https://api.screenrig.ai/mcp 和 OAuth 认证创建一个应用（连接器）。连接时 ChatGPT 会打开同意页面。ChatGPT 还可以 订阅事件，例如屏幕离线，并在事件发生时通知你。

连接 Grok

在 Grok 网页版中，添加服务器 URL https://api.screenrig.ai/mcp 的自定义连接器。请求 OAuth 客户端 ID 时，输入 screenrig-grok-web 并留空客户端密钥。Grok 会打开同意页面。

在 Grok Build 中，添加服务器 URL 作为远程 HTTP 服务器。Grok Build 第一次使用服务器时会打开浏览器登录。

通过 API 使用服务器

Claude、OpenAI 和 xAI API 每次请求连接远程 MCP 服务器，需提供授权值。使用 服务客户端：先用 resource=https://api.screenrig.ai/mcp 请求令牌，再与服务器 URL 一起传递。

curl -s https://api.screenrig.ai/oauth/token \
  -u "$SCREENRIG_CLIENT_ID:$SCREENRIG_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d resource=https://api.screenrig.ai/mcp

该请求的令牌仅在 /mcp 有效，持续 15 分钟，作用于服务客户端项目，具访问级别和能力。过期后请求新令牌。

工具

每个工具名称都以screenrig_开头。工具调用运行与 CLI 和 REST API 相同的处理程序，具有相同的项目隔离、权限、额度扣除、速率限制、幂等性和修订检查。

工具的行为方式

• 分页。 列表工具返回一页，最新的优先（按键顺序 K/V）。传回非空next_cursor作为after，使用相同过滤器，获取下一页。
• 重试。 写入操作接受一个可选的 idempotency_key。重用它可安全重试相同写入；省略则开始新请求。配对、提示、截图、图像生成、邀请、浏览器链接、操作取消和反馈均需此参数，且其输入模式会说明。
• 修订。 写入操作接受一个可选的 revision。过时的修订会被拒绝：请重新读取资源，重新应用更改并重试。
• 审核。播放列表和屏幕更改工具接受可选的 review_note（最多 280 个字符），供审核者阅读。等待审核的更改会返回 pending_review 正文：请告知用户该更改正在等待其批准，并提供审核的 url。更改已批准媒体标签的 media_update 会返回带有 review_state pending 的条目：屏幕保留其已批准的标签，其审核将在几秒内出现在审核中。media_restore 接受相同的 review_note 并返回 pending_review 正文：在有人批准之前，媒体继续播放其当前文件。
• 播放内容。 屏幕播放一个堆栈中生效的最高层级：其接管、覆盖它的活动（priority 0 到 100，较高者优先，然后是最新的）、按顺序排列的播放列表排程条目，最后是其分配的播放列表。活动和排程条目接受与 CLI 相同的规则，包括 monthly、dates、except 和 interaction。screen_get 报告 effective_playlist，其 source 为 takeover、campaign、schedule 或 default。schedule_calendar 接受 from 和 to（相隔最多 93 天）以及 screen_id、folder_id、tag 或 campaign_id 之一：它把堆栈相同的屏幕分组，并列出每个层级的时间段（plays、partial、outranked、conditional）和冲突（同一优先级的两个活动同时生效、永远不播放的层级）。活动写入需要管理权限，且从不变成审核：Propose 应用只列出活动读取工具。
• 截图。 screen_screenshot 等待最多60秒并返回捕获的image/webp图像内容。screen_screenshot_current 返回最后准备好的静态图像及其captured_at时间，无需请求新捕获。
• 通知规则。 notification_create 和 notification_update 接受 min_severity（info、warning 或 error）、severity（条件到级别，例如 {"not_playing": "error"}）、active_hours（timezone、windows，以及 outside、hold 或 drop）和 audience（活动受众的规则，取代 screen_tags）。reach_drop（screens、percent）设定活动触达减少多大幅度时 reach_dropped 条件才发出通知；它仅对该条件有效。reach_dropped 和 group_empty 监视活动，因此 screen_tags 和 audience 永远不会限制它们。更新时，null 会清除其中每一项。被保留或跳过的提醒出现在 notification_deliveries 中。
• 秘密保持安全。 Webhook结果永远不包含签名密钥，并将每个接收URL简化为其源。邀请仅通过电子邮件发送，因此邀请链接不会传递给模型。
• 撤销中。 project_credential_revoke 断开发起调用的智能体会话。需要 confirmation: "REVOKE"，且 allow_last_agent: true 用于断开项目最后一个活跃智能体。项目及其内容保持不变。连接的应用通过 https://api.screenrig.ai/oauth/revoke 结束自身会话，或由人员在访问页面断开。
• 错误。 拒绝调用会返回工具错误，其结构化内容是 REST API 的问题文档，包含 code、detail 和 status。结果的 screenrig/result 元数据携带 http_status，以及服务器发送时的 etag、credit_remaining 或 retry_after。

资源

项目资源暴露私有元数据，且永不缓存。服务器还为 MCP 应用主机中的交互卡提供 HTML UI 资源。

事件

服务器实现 MCP 事件及 webhook 传递。应用订阅事件，screenRIG 在事件发生时向应用的 HTTPS 回调 POST 签名消息，应用可无需轮询告知屏幕离线或截图准备好。订阅需 OAuth 会话：连接的应用或服务客户端。只读会话可订阅，因事件为读取。

提议更改的应用从 review.requested、review.approved、review.rejected 和 review.changes_requested 学习每个决策。

数据仅包含ID和状态。使用工具读取完整记录，例如screenrig_screen_get或screenrig_screen_screenshot_current。

列出并订阅

events/list 返回此会话可订阅的事件，每个事件带有 inputSchema 和 payloadSchema。屏幕事件可选带 screenId 参数以跟踪单个屏幕。events/subscribe 接收事件、参数和回调：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "events/subscribe",
  "params": {
    "name": "screen.offline",
    "arguments": { "screenId": "scr_LOBBY" },
    "delivery": {
      "mode": "webhook",
      "url": "https://receiver.example.com/screenrig",
      "secret": "whsec_BASE64_OF_32_RANDOM_BYTES"
    },
    "ttlMs": 86400000
  }
}

• 密钥 属于你：whsec_ 后跟 24 至 64 字节随机数的 base64 编码。用于签署每次交付。
• 回调 是公共地址上的 HTTPS URL，无重定向。
• 结果 包含订阅 id（sub_…）、refreshBefore 和 cursor: null。交付从现在开始；无重放。
• 有效期。ttlMs请求 5 分钟至 24 小时；默认 1 小时，null为 24 小时。在refreshBefore之前使用相同名称、参数和 URL 重新订阅以延长；ID 保持不变，结果报告deliveryStatus。刷新时的新密钥与旧密钥同时签名 10 分钟。
• 取消订阅 使用 events/unsubscribe 和相同的名称、参数及 delivery.url。

组织跨其所有项目最多持有 100 个订阅，一个会话每小时最多订阅 120 次。订阅在其会话或服务客户端被撤销、应用断开连接、人员停用或项目删除时结束，权限每 15 分钟重新检查。

验证回调

会话首次订阅回调 URL 时发送签名验证 POST：

{ "type": "verification", "challenge": "RANDOM_CHALLENGE" }

在5秒内以相同的JSON挑战响应2xx：

{ "challenge": "RANDOM_CHALLENGE" }

检查失败时，订阅调用返回 JSON-RPC 错误 -32015，其 data.reason 为 challenge_failed、timeout、connection_refused、tls_error、http_4xx 或 http_5xx。

接收交付

每次投递都是一个POST事件，最大 256 KiB：

{
  "eventId": "evt_EVENT",
  "name": "screen.offline",
  "timestamp": "2026-10-08T14:02:11Z",
  "data": { "screenId": "scr_LOBBY", "screenName": "Lobby" },
  "cursor": null
}

交付遵循 Standard Webhooks：

要验证，请将 whsec_ 后的 base64 解码为密钥，计算 HMAC-SHA256，内容包括 webhook-id、.、webhook-timestamp、. 和原始正文，并以恒定时间将其 base64 与每个 v1, 值比较。拒绝与本地时间相差超过五分钟的时间戳：

import { createHmac, timingSafeEqual } from "node:crypto";

export function verified(secret, headers, rawBody) {
  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.`).update(rawBody).digest();
  return headers["webhook-signature"].split(" ").some((entry) => {
    const [version, signature] = entry.split(",");
    const given = Buffer.from(signature ?? "", "base64");
    return version === "v1" && given.length === expected.length && timingSafeEqual(given, expected);
  });
}

快速响应2xx。失败的投递会重试15分钟；410 Gone或413 Payload Too Large会立即停止。

为此使用 CLI

这些步骤移动文件或密钥，或在你的机器上运行，因此它们保留在捆绑的 CLI中：

相关

• 启动：安装官方插件及其捆绑的 CLI。
• 身份验证：会话、只读、提议和管理，以及访问页面。
• 服务客户端：服务器、脚本和API连接器的令牌。
• CLI 参考：所有命令，遵循上述工具相同约定。
• API 参考：工具共享的 REST 协议和问题类型。