Conecte um cliente MCP a suas telas

O servidor

O servidor não mantém sessões. Recusa GET, DELETE, Mcp-Session-Id e cookies. Cada requisição autentica-se sozinha, então um app desconectado para de funcionar na próxima chamada. Requisições são limitadas a 4 MiB.

O plugin oficial mantém o fluxo completo: ele envia arquivos e empacota aplicativos na sua máquina. Use o servidor MCP quando seu cliente chamar ferramentas via MCP, e mantenha o CLI incluído para o trabalho local.

Conectar com OAuth

Clientes MCP encontram o login sozinhos. Uma solicitação sem token responde 401 com WWW-Authenticate: Bearer resource_metadata="https://api.screenrig.ai/.well-known/oauth-protected-resource/mcp", e esse documento nomeia o servidor de autorização, https://api.screenrig.ai. Seus metadados estão em https://api.screenrig.ai/.well-known/oauth-authorization-server.

1. Adicione a URL do servidor ao seu cliente. O cliente abre a página de consentimento screenRIG no seu navegador.
2. Faça login no dashboard se necessário. A página mostra o nome e domínio do aplicativo conforme declarado pelo app, se o screenRIG o registrou e para onde seu navegador retorna.
3. Escolha o projeto, Somente leitura, Propor ou Gerenciar, e as capacidades, depois escolha Conectar app e confirme com sua passkey.
4. Seu navegador retorna ao app, que agora tem sua própria sessão. Ele renova essa sessão sozinho; cada token de acesso dura 15 minutos.

Conecte apenas um aplicativo que você está configurando agora. Os clientes se identificam com um Documento de Metadados de ID do Cliente (CIMD), portanto não há etapa de registro. A autorização usa PKCE com S256, URIs de redirecionamento exatos e um código de uso único que dura 60 segundos.

O app aparece em Apps conectados na página Acesso do dashboard. Desconectar ali encerra em segundos; reconecte para escolher outro projeto ou nível de acesso. Veja Autenticação para as sessões por trás disso.

O host CLI e MCP mantêm sessões separadas. Não copie o token salvo do CLI para a configuração do MCP, cole credenciais em uma conversa ou as passe para um cartão incorporado. O host gerencia seus próprios tokens OAuth e atualização.

O plugin oficial solicita access:manage, screens, content, playlists e reports; o usuário aprova o acesso durante o login. Uma captura de tela nova requer acesso Propor ou Gerenciar e a capacidade screens. Uma conexão existente somente leitura precisa de consentimento renovado antes de solicitar uma captura.

Hosts de MCP Apps podem renderizar cartões interativos de tela, mídia e playlist pela conexão autenticada. O cartão usa a ponte MCP Apps do host; não contém credencial e não chama a API diretamente. Hosts sem renderização MCP Apps ainda podem consumir texto de ferramenta e dados estruturados.

Somente leitura, Propor e Gerenciar

Aplicativos conectados padrão para Somente leitura. Um aplicativo Somente leitura lista apenas ferramentas de leitura, e chamar uma ferramenta acima do nível da sessão responde HTTP 403 insufficient_access com WWW-Authenticate: Bearer error="insufficient_scope" e o scope que permite isso. URLs de receptor webhook aparecem como ocultos para Somente leitura.

Um app Propose também lista as ferramentas que enviam, anotam e propõem. Suas mudanças de playlist e tela retornam status: "pending_review" com a id e url da revisão em vez de aplicar, e uma pessoa as aprova no Reviews do dashboard. Quando o projeto requer revisão para mudanças de agente, todo app funciona no máximo em Propose. Para permitir que o app faça mudanças diretamente, desconecte-o e conecte-o novamente com Manage.

tools/list retorna apenas as ferramentas que o nível de acesso e capacidades da sessão permitem. Os direitos do plano do projeto se aplicam por cima, exatamente como no CLI. Cada chamada de ferramenta é uma solicitação de agente, cobrada como qualquer outra.

Conectar Claude

No Claude (web, desktop ou mobile), adicione um conector personalizado com a URL https://api.screenrig.ai/mcp e conecte-o. O Claude abre a página de consentimento.

No Claude Code, adicione o servidor, depois autentique a partir de /mcp:

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

Conectar ChatGPT

No ChatGPT, crie um app (conector) com a URL do servidor https://api.screenrig.ai/mcp e autenticação OAuth. O ChatGPT abre a página de consentimento ao conectar. O ChatGPT também pode assinar eventos, como uma tela ficar offline, e avisar quando isso acontecer.

Conectar Grok

No Grok na web, adicione um conector personalizado com a URL do servidor https://api.screenrig.ai/mcp. Quando pedir um ID de cliente OAuth, insira screenrig-grok-web e deixe o segredo do cliente vazio. O Grok abre a página de consentimento.

No Grok Build, adicione a URL do servidor como um servidor HTTP remoto. O Grok Build abre o login no navegador na primeira vez que usa o servidor.

Use o servidor via API

As APIs Claude, OpenAI e xAI conectam-se a um servidor MCP remoto por requisição, com um valor de autorização que você fornece. Use um cliente de serviço: peça um token com resource=https://api.screenrig.ai/mcp, então passe-o com a URL do 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

Um token dessa requisição funciona apenas em /mcp, dura 15 minutos e age no projeto do cliente de serviço com seu nível de acesso e capacidades. Peça um novo quando expirar.

Ferramentas

Cada nome de ferramenta começa com screenrig_. Chamadas de ferramenta executam os mesmos manipuladores que a CLI e a REST API, com o mesmo isolamento de projeto, permissões, cobranças de crédito, limites de taxa, idempotência e verificações de revisão.

Como as ferramentas se comportam

• Paginação. Ferramentas de listagem retornam uma página, a mais nova primeiro (K/V em ordem de chave). Passe um next_cursor não nulo de volta como after, com os mesmos filtros, para a próxima página.
• Tentativas. Escritas aceitam um idempotency_key opcional. Reutilize-o para tentar a mesma escrita com segurança; omita para iniciar uma nova solicitação. Pareamento, notificações, capturas de tela, geração de imagens, convites, links de navegador, cancelamentos de operação e feedback exigem um, e seus esquemas de entrada indicam isso.
• Revisões. Escritas aceitam um revision opcional. Uma revisão obsoleta é recusada: leia o recurso novamente, reaplique a alteração e tente novamente.
• Revisões. As ferramentas de alteração de playlist e de tela aceitam um review_note opcional, de no máximo 280 caracteres, que o revisor lê. Uma alteração que aguarda revisão retorna o corpo pending_review: diga ao usuário que ela aguarda a aprovação dele e informe a ele o url da revisão. Um media_update que altera as tags de uma mídia aprovada retorna o item com review_state pending: as telas mantêm as tags aprovadas, e a revisão aparece em Revisões em poucos segundos. Um media_restore aceita o mesmo review_note e retorna o corpo pending_review: a mídia continua reproduzindo seu arquivo até que uma pessoa aprove.
• O que é reproduzido. Uma tela reproduz o nível mais alto que vigora em uma pilha: seu takeover, as campanhas que a alcançam (priority de 0 a 100, maior primeiro, depois a mais recente), as entradas da programação de playlist em ordem e, por fim, sua playlist atribuída. Campanhas e entradas de programação aceitam as mesmas regras do CLI, incluindo monthly, dates, except e interaction. screen_get reporta effective_playlist com source takeover, campaign, schedule ou default. schedule_calendar recebe from e to (com no máximo 93 dias de diferença) e um entre screen_id, folder_id, tag ou campaign_id: agrupa telas com pilhas idênticas e lista os intervalos de cada nível (plays, partial, outranked, conditional) e os conflitos (duas campanhas de mesma prioridade vigorando ao mesmo tempo, um nível que nunca é reproduzido). As gravações de campanha precisam de acesso Gerenciar e nunca se tornam revisões: um app Propor lista apenas as ferramentas de leitura de campanha.
• Capturas de tela. screen_screenshot espera até 60 segundos e retorna a captura como conteúdo de imagem image/webp. screen_screenshot_current retorna a última imagem pronta e seu tempo captured_at sem solicitar uma nova captura.
• Regras de notificação. notification_create e notification_update aceitam min_severity (info, warning ou error), severity (condição para nível, como {"not_playing": "error"}), active_hours (timezone, windows e outside, hold ou drop) e audience (as regras de um público-alvo de campanha, no lugar de screen_tags). reach_drop (screens, percent) define a partir de qual tamanho de queda no alcance de uma campanha uma condição reach_dropped notifica; é válido somente com essa condição. reach_dropped e group_empty observam campanhas, portanto screen_tags e audience nunca as limitam. Na atualização, null limpa cada um. Um aviso retido ou ignorado aparece em notification_deliveries.
• Segredos ficam fora. Resultados de webhook nunca carregam o segredo de assinatura e reduzem cada URL de receptor à sua origem. Convites são enviados apenas por e-mail, então nenhum link de convite chega ao modelo.
• Revogando. project_credential_revoke desconecta o agente cuja sessão fez a chamada. Requer confirmation: "REVOKE", e allow_last_agent: true para desconectar o último agente ativo do projeto. O projeto e seu conteúdo permanecem. Um aplicativo conectado encerra sua própria sessão por meio de https://api.screenrig.ai/oauth/revoke, ou uma pessoa o desconecta na página de Acesso.
• Erros. Uma chamada recusada retorna um erro de ferramenta cujo conteúdo estruturado é o documento de problema da API REST, com code, detail e status. Os metadados do resultado screenrig/result carregam http_status, e etag, credit_remaining ou retry_after quando o servidor os enviou.

Recursos

Recursos do projeto expõem metadados privados e nunca são armazenados em cache. O servidor também fornece um recurso de UI HTML para cartões interativos em hosts de MCP Apps.

Eventos

O servidor implementa MCP Events com entrega via webhook. Um app se inscreve em um evento, e screenRIG envia uma mensagem assinada para o callback HTTPS do app quando ele ocorre, para que o app possa informar que uma tela ficou offline ou que um screenshot está pronto sem polling. Inscrição requer sessão OAuth: um app conectado ou um cliente de serviço. Sessões somente leitura podem se inscrever, pois eventos são leituras.

Um app que propõe mudanças aprende cada decisão de review.requested, review.approved, review.rejected e review.changes_requested.

Dados carregam apenas ids e estados. Leia o registro completo com uma ferramenta, como screenrig_screen_get ou screenrig_screen_screenshot_current.

Listar e assinar

events/list retorna os eventos que esta sessão pode assinar, cada um com um inputSchema e um payloadSchema. Eventos de tela aceitam um argumento screenId opcional para seguir uma tela. events/subscribe recebe o evento, seus argumentos e o callback:

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

• O segredo é seu: whsec_ seguido por base64 de 24 a 64 bytes aleatórios. Ele assina cada entrega.
• O callback é uma URL HTTPS em um endereço público, sem redirecionamentos.
• O resultado carrega a assinatura id (sub_…), refreshBefore e cursor: null. As entregas começam agora; não há reprodução.
• Vitalício. ttlMs solicita de 5 minutos a 24 horas; o padrão é uma hora, e null obtém 24 horas. Assine novamente com o mesmo nome, argumentos e URL antes de refreshBefore para estender; o id permanece o mesmo, e o resultado informa deliveryStatus. Um novo segredo em uma atualização assina junto com o antigo por 10 minutos.
• Cancelar inscrição com events/unsubscribe e o mesmo nome, argumentos e delivery.url.

Uma organização mantém até 100 assinaturas em todos os seus projetos, e uma sessão pode assinar 120 vezes por hora. Uma assinatura termina quando sua sessão ou cliente de serviço é revogado, seu app desconectado, sua pessoa desativada ou seu projeto excluído, e sua autoridade é verificada a cada 15 minutos.

Verificar o callback

A primeira assinatura de uma sessão para uma URL de callback envia um POST de verificação assinado:

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

Responda 2xx dentro de 5 segundos com o mesmo desafio em JSON:

{ "challenge": "RANDOM_CHALLENGE" }

Uma verificação falha responde a chamada subscribe com erro JSON-RPC -32015, cujo data.reason é challenge_failed, timeout, connection_refused, tls_error, http_4xx ou http_5xx.

Receber entregas

Cada entrega é um POST de um evento, com no máximo 256 KiB:

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

Entregas seguem Standard Webhooks:

Para verificar, decodifique o base64 após whsec_ na chave, calcule HMAC-SHA256 sobre webhook-id, ., webhook-timestamp, . e o corpo bruto, e compare seu base64 com cada valor v1, em tempo constante. Rejeite um timestamp com mais de cinco minutos de diferença do seu relógio:

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 rapidamente. Uma entrega falhada é tentada por 15 minutos; 410 Gone ou 413 Payload Too Large a interrompe imediatamente.

Use o CLI para estes

Estas etapas movem arquivos ou segredos, ou são executadas na sua máquina, portanto permanecem no CLI incluído:

Relacionado

• Iniciar: instale o plugin oficial e seu CLI incluído.
• Autenticação: sessões, Somente leitura, Propor e Gerenciar, e a página de Acesso.
• Clientes de serviço: tokens para servidores, scripts e conectores de API.
• Referência CLI: todos os comandos, com as mesmas convenções das ferramentas acima.
• Referência da API: o contrato REST e os tipos de problemas compartilhados pelas ferramentas.