Conecte un cliente MCP a sus pantallas

El servidor

El servidor no mantiene sesiones. Rechaza GET, DELETE, Mcp-Session-Id y cookies. Cada solicitud se autentica por sí sola, por lo que una aplicación desconectada deja de funcionar en su siguiente llamada. Las solicitudes están limitadas a 4 MiB.

El plugin oficial mantiene el flujo completo: sube archivos y empaqueta aplicaciones en su máquina. Use el servidor MCP cuando su cliente llame a herramientas mediante MCP, y mantenga la CLI incluida para el trabajo local.

Conectar con OAuth

Los clientes MCP encuentran el inicio de sesión por sí mismos. Una solicitud sin token responde 401 con WWW-Authenticate: Bearer resource_metadata="https://api.screenrig.ai/.well-known/oauth-protected-resource/mcp", y ese documento nombra el servidor de autorización, https://api.screenrig.ai. Sus metadatos están en https://api.screenrig.ai/.well-known/oauth-authorization-server.

1. Agregue la URL del servidor a su cliente. El cliente abre la página de consentimiento de screenRIG en su navegador.
2. Inicie sesión en el panel si es necesario. La página muestra el nombre y dominio de la aplicación tal como los declara la aplicación, ya sea que screenRIG la haya registrado o no, y a dónde regresa su navegador.
3. Elija el proyecto, Solo lectura, Proponer o Administrar, y las capacidades, luego elija Conectar app y confirme con su passkey.
4. Su navegador vuelve a la aplicación, que ahora tiene su propia sesión. Renueva esa sesión automáticamente; cada token de acceso dura 15 minutos.

Conecte solo una aplicación que esté configurando usted mismo, ahora mismo. Los clientes se identifican con un Documento de Metadatos de ID de Cliente (CIMD), por lo que no hay paso de registro. La autorización usa PKCE con S256, URIs de redirección exactas y un código de un solo uso que dura 60 segundos.

La aplicación aparece bajo Aplicaciones conectadas en la página Acceso del panel. Desconectar allí termina la conexión en segundos; vuelva a conectarla para elegir un proyecto o nivel de acceso diferente. Vea Autenticación para las sesiones detrás de esto.

El host de CLI y MCP mantiene sesiones separadas. No copie el token guardado del CLI en la configuración del MCP, pegue credenciales en una conversación ni páselas a una tarjeta incrustada. El host maneja sus propios tokens OAuth y su renovación.

El plugin oficial solicita access:manage, screens, content, playlists y reports; el usuario aprueba el acceso durante el inicio de sesión. Una captura de pantalla nueva requiere acceso Propose o Manage y la capacidad screens. Una conexión existente de solo lectura necesita consentimiento renovado antes de solicitar una captura.

Los hosts de MCP Apps pueden renderizar tarjetas interactivas de pantalla, medios y listas de reproducción a través de la conexión autenticada. La tarjeta usa el puente MCP Apps del host; no contiene credenciales ni llama a la API directamente. Hosts sin renderizado MCP Apps aún pueden consumir texto de herramientas y datos estructurados.

Solo lectura, proponer y administrar

Las aplicaciones conectadas predeterminan Solo lectura. Una aplicación Solo lectura lista solo herramientas de lectura, y llamar a una herramienta por encima del nivel de la sesión responde HTTP 403 insufficient_access con WWW-Authenticate: Bearer error="insufficient_scope" y el scope que lo permite. Las URLs receptoras de webhook se muestran redactadas para Solo lectura.

Una aplicación Propose también lista las herramientas que cargan, anotan y proponen. Sus cambios de lista de reproducción y pantalla devuelven status: "pending_review" con la id y url de la revisión en lugar de aplicarlos, y una persona los aprueba en Revisiones del dashboard. Cuando el proyecto requiere revisión para cambios de agente, todas las aplicaciones trabajan como máximo en Propose. Para permitir que la aplicación haga cambios directamente, desconéctela y conéctela nuevamente con Manage.

tools/list devuelve solo las herramientas que el nivel de acceso y capacidades de la sesión permiten. Los derechos del plan del proyecto se aplican además, exactamente como para la CLI. Cada llamada a herramienta es una solicitud de agente, facturada como cualquier otra.

Conectar Claude

En Claude (web, escritorio o móvil), agregue un conector personalizado con la URL https://api.screenrig.ai/mcp y conéctelo. Claude abre la página de consentimiento.

En Claude Code, agregue el servidor, luego autentíquese desde /mcp:

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

Conectar ChatGPT

En ChatGPT, cree una app (conector) con la URL del servidor https://api.screenrig.ai/mcp y autenticación OAuth. ChatGPT abre la página de consentimiento cuando lo conecta. ChatGPT también puede suscribirse a eventos, como que una pantalla se desconecte, y avisarle cuando ocurran.

Conectar Grok

En Grok en la web, agregue un conector personalizado con la URL del servidor https://api.screenrig.ai/mcp. Cuando pida un ID de cliente OAuth, ingrese screenrig-grok-web y deje el secreto del cliente vacío. Grok abre la página de consentimiento.

En Grok Build, agregue la URL del servidor como un servidor HTTP remoto. Grok Build abre el inicio de sesión del navegador la primera vez que usa el servidor.

Utilice el servidor desde una API

Las APIs de Claude, OpenAI y xAI se conectan a un servidor MCP remoto por solicitud, con un valor de autorización que usted suministra. Use un cliente de servicio: solicite un token con resource=https://api.screenrig.ai/mcp, luego páselo con la URL del servidor.

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

Un token de esa solicitud funciona solo en /mcp, dura 15 minutos y actúa en el proyecto del cliente del servicio con su nivel de acceso y capacidades. Solicite uno nuevo cuando expire.

Herramientas

Cada nombre de herramienta comienza con screenrig_. Las llamadas a herramientas ejecutan los mismos manejadores que el CLI y la API REST, con el mismo aislamiento de proyecto, permisos, cargos de crédito, límites de tasa, idempotencia y verificaciones de revisión.

Cómo se comportan las herramientas

• Paginación. Las herramientas de lista devuelven una página, la más nueva primero (K/V en orden de clave). Pase un next_cursor no nulo como after, con los mismos filtros, para la siguiente página.
• Reintentos. Las escrituras aceptan un idempotency_key opcional. Reutilícelo para reintentar la misma escritura de forma segura; omítalo para iniciar una solicitud nueva. El emparejamiento, notificaciones, capturas de pantalla, generación de imágenes, invitaciones, enlaces de navegador, cancelaciones de operaciones y comentarios requieren uno, y sus esquemas de entrada lo indican.
• Revisiones. Las escrituras aceptan un revision opcional. Se rechaza una revisión obsoleta: lea el recurso nuevamente, vuelva a aplicar el cambio y reintente.
• Revisiones. Las herramientas de cambio de lista de reproducción y de pantalla aceptan un review_note opcional, de 280 caracteres como máximo, que lee el revisor. Un cambio que espera revisión devuelve el cuerpo pending_review: diga al usuario que espera su aprobación y proporciónele el url de la revisión. Un media_update que cambia las etiquetas de un contenido multimedia aprobado devuelve el elemento con review_state pending: las pantallas conservan sus etiquetas aprobadas y su revisión aparece en Revisiones en unos segundos. Un media_restore acepta el mismo review_note y devuelve el cuerpo pending_review: el contenido multimedia sigue reproduciendo su archivo hasta que una persona apruebe.
• Qué se reproduce. Una pantalla reproduce el nivel superior que rige en una pila: su toma de control, las campañas que la alcanzan (priority de 0 a 100, de mayor a menor, luego la más nueva), las entradas de su programación de lista de reproducción en orden y, por último, su lista de reproducción asignada. Las campañas y las entradas de programación aceptan las mismas reglas que la CLI, entre ellas monthly, dates, except y interaction. screen_get informa effective_playlist con source takeover, campaign, schedule o default. schedule_calendar recibe from y to (con un máximo de 93 días de diferencia) y uno de screen_id, folder_id, tag o campaign_id: agrupa las pantallas con pilas idénticas y lista los tramos de cada nivel (plays, partial, outranked, conditional) y los conflictos (dos campañas de la misma prioridad que rigen a la vez, un nivel que nunca se reproduce). Las escrituras de campañas requieren acceso de administración y nunca se convierten en revisiones: una aplicación con acceso Proponer solo lista las herramientas de lectura de campañas.
• Capturas de pantalla. screen_screenshot espera hasta 60 segundos y devuelve la captura como contenido de imagen image/webp. screen_screenshot_current devuelve la última imagen fija lista y su tiempo captured_at sin solicitar una nueva captura.
• Reglas de notificación. notification_create y notification_update aceptan min_severity (info, warning o error), severity (condición a nivel, como {"not_playing": "error"}), active_hours (timezone, windows y outside, hold o drop) y audience (las reglas de una audiencia de campaña, en lugar de screen_tags). reach_drop (screens, percent) define qué tan grande debe ser una caída en el alcance de una campaña para que una condición reach_dropped notifique; solo es válido con esa condición. reach_dropped y group_empty vigilan campañas, por lo que screen_tags y audience nunca las limitan. Al actualizar, null borra cada uno. Un aviso retenido u omitido aparece en notification_deliveries.
• Los secretos permanecen fuera. Los resultados del webhook nunca llevan el secreto de firma y reducen cada URL receptora a su origen. Las invitaciones se envían solo por correo electrónico, por lo que ningún enlace de invitación llega al modelo.
• Revocando. project_credential_revoke desconecta al agente cuya sesión hizo la llamada. Requiere confirmation: "REVOKE", y allow_last_agent: true para desconectar al último agente activo del proyecto. El proyecto y su contenido permanecen. Una aplicación conectada termina su propia sesión mediante https://api.screenrig.ai/oauth/revoke, o una persona la desconecta en la página de Acceso.
• Errores. Una llamada rechazada devuelve un error de herramienta cuyo contenido estructurado es el documento de problema de la API REST, con code, detail y status. Los metadatos screenrig/result del resultado llevan http_status, y etag, credit_remaining o retry_after cuando el servidor los envió.

Recursos

Los recursos del proyecto exponen metadatos privados y nunca se almacenan en caché. El servidor también proporciona un recurso de interfaz HTML para tarjetas interactivas en hosts de aplicaciones MCP.

Eventos

El servidor implementa MCP Events con entrega por webhook. Una aplicación se suscribe a un evento, y screenRIG envía un mensaje firmado al callback HTTPS de la aplicación cuando ocurre, para que la aplicación pueda informarle que una pantalla se desconectó o que una captura de pantalla está lista sin sondear. La suscripción requiere una sesión OAuth: una aplicación conectada o un cliente de servicio. Las sesiones de solo lectura pueden suscribirse, ya que los eventos son lecturas.

Una app que propone cambios aprende cada decisión de review.requested, review.approved, review.rejected y review.changes_requested.

Los datos solo contienen identificadores y estados. Lea el registro completo con una herramienta, como screenrig_screen_get o screenrig_screen_screenshot_current.

Listar y suscribirse

events/list devuelve los eventos a los que esta sesión puede suscribirse, cada uno con un inputSchema y un payloadSchema. Los eventos de pantalla toman un argumento screenId opcional para seguir una pantalla. events/subscribe toma el evento, sus argumentos y la devolución de llamada:

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

• El secreto es suyo: whsec_ seguido por base64 de 24 a 64 bytes aleatorios. Firma cada entrega.
• El callback es una URL HTTPS en una dirección pública, sin redirecciones.
• El resultado incluye la suscripción id (sub_…), refreshBefore y cursor: null. Las entregas comienzan ahora; no hay repetición.
• Duración. ttlMs solicita de 5 minutos a 24 horas; el valor predeterminado es una hora, y null obtiene 24 horas. Suscríbase de nuevo con el mismo nombre, argumentos y URL antes de refreshBefore para extenderla; el id permanece igual y el resultado informa deliveryStatus. Un nuevo secreto en una actualización firma junto con el antiguo durante 10 minutos.
• Darse de baja con events/unsubscribe y el mismo nombre, argumentos y delivery.url.

Una organización contiene hasta 100 suscripciones en todos sus proyectos, y una sesión puede suscribirse 120 veces por hora. Una suscripción termina cuando su sesión o cliente de servicio es revocado, su app se desconecta, su persona se desactiva o su proyecto se elimina, y su autoridad se verifica cada 15 minutos.

Verificar la devolución de llamada

La primera suscripción desde una sesión a una URL de callback envía un POST de verificación firmado:

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

Responda 2xx en 5 segundos con el mismo desafío en JSON:

{ "challenge": "RANDOM_CHALLENGE" }

Una comprobación fallida responde a la llamada subscribe con error JSON-RPC -32015, cuyo data.reason es challenge_failed, timeout, connection_refused, tls_error, http_4xx o http_5xx.

Recibir entregas

Cada entrega es un POST de un evento, de hasta 256 KiB:

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

Las entregas siguen Standard Webhooks:

Para verificar, decodifique el base64 después de whsec_ en la clave, calcule HMAC-SHA256 sobre webhook-id, ., webhook-timestamp, . y el cuerpo sin procesar, y compare su base64 con cada valor v1, en tiempo constante. Rechace una marca de tiempo con más de cinco minutos de diferencia con su reloj:

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);
  });
}

Responda 2xx rápidamente. Una entrega fallida se reintenta durante 15 minutos; 410 Gone o 413 Payload Too Large la detienen de inmediato.

Use la CLI para estos

Estos pasos mueven archivos o secretos, o se ejecutan en su máquina, por lo que permanecen en el CLI incluido:

Relacionado

• Comenzar: instale el plugin oficial y su CLI incluida.
• Autenticación: sesiones, solo lectura, proponer y administrar, y la página de acceso.
• Clientes del servicio: tokens para servidores, scripts y conectores API.
• Referencia CLI: todos los comandos, con las mismas convenciones que las herramientas anteriores.
• Referencia API: el contrato REST y los tipos de problemas que comparten las herramientas.