Connetti un client MCP a i tuoi schermi

Il server

Il server non mantiene sessioni. Rifiuta GET, DELETE, Mcp-Session-Id e cookie. Ogni richiesta si autentica da sola, quindi un’app disconnessa smette di funzionare alla chiamata successiva. Le richieste sono limitate a 4 MiB.

Il plugin ufficiale gestisce l’intero flusso di lavoro: carica file e impacchetta applicazioni sulla tua macchina. Usa il server MCP quando il client chiama strumenti tramite MCP e conserva il CLI incluso per il lavoro locale.

Connetti con OAuth

I client MCP trovano l’accesso da soli. Una richiesta senza token risponde 401 con WWW-Authenticate: Bearer resource_metadata="https://api.screenrig.ai/.well-known/oauth-protected-resource/mcp", e quel documento nomina il server di autorizzazione, https://api.screenrig.ai. I suoi metadati sono a https://api.screenrig.ai/.well-known/oauth-authorization-server.

1. Aggiungi l’URL del server al client. Il client apre la pagina di consenso screenRIG nel browser.
2. Accedi al dashboard se necessario. La pagina mostra il nome e il dominio dell’app come dichiarati dall’app stessa, se registrata da screenRIG, e dove il browser ritorna.
3. Scegli il progetto, Solo lettura, Proponi o Gestisci, e le capacità, poi scegli Connetti app e conferma con la tua passkey.
4. Il tuo browser torna all’app, che ora ha la propria sessione. Essa si rinnova da sola; ogni token di accesso dura 15 minuti.

Connetti solo un’app che stai configurando tu stesso, adesso. I client si identificano con un Documento Metadata Client ID (CIMD), quindi non c’è una fase di registrazione. L’autorizzazione usa PKCE con S256, URI di reindirizzamento esatti e un codice monouso valido 60 secondi.

L’app appare sotto App connesse nella pagina Accesso della dashboard. Disconnetti lì termina la connessione in pochi secondi; riconnettila per scegliere un progetto o livello di accesso diverso. Vedi Autenticazione per le sessioni dietro di essa.

Il CLI e l’host MCP mantengono sessioni separate. Non copiare il token salvato dal CLI nella configurazione MCP, incollare credenziali in una conversazione o passarle a una scheda incorporata. L’host gestisce i propri token OAuth e il refresh.

Il plugin ufficiale richiede access:manage, screens, content, playlists e reports; l’utente approva l’accesso durante l’accesso. Uno screenshot nuovo richiede accesso Proponi o Gestisci e la capacità screens. Una connessione esistente in sola lettura necessita di consenso rinnovato prima di richiedere una cattura.

Gli host MCP Apps possono renderizzare schede interattive di schermo, media e playlist tramite la connessione autenticata. La scheda usa il bridge MCP Apps dell’host; non contiene credenziali e non chiama direttamente l’API. Gli host senza rendering MCP Apps possono comunque consumare testo strumento e dati strutturati.

Solo lettura, proporre e gestire

Le app connesse sono impostate di default su Solo lettura. Un’app Solo lettura elenca solo strumenti di lettura, e chiamare uno strumento oltre il livello della sessione risponde con HTTP 403 insufficient_access con WWW-Authenticate: Bearer error="insufficient_scope" e il scope che lo autorizza. Gli URL dei webhook per ricezione sono oscurati per Solo lettura.

Un’app Propose elenca anche gli strumenti che caricano, annotano e propongono. Le sue modifiche a playlist e schermo restituiscono status: "pending_review" con la id e url della revisione invece di applicarle, e una persona le approva nel dashboard Reviews. Quando il progetto richiede revisione per modifiche agent, ogni app lavora al massimo in Propose. Per permettere all’app di modificare direttamente, disconnettila e riconnettila con Manage.

tools/list restituisce solo gli strumenti consentiti dal livello di accesso e dalle capacità della sessione. Si applicano i diritti del piano progetto, esattamente come per la CLI. Ogni chiamata a uno strumento è una richiesta agente, fatturata come le altre.

Connetti Claude

In Claude (web, desktop o mobile), aggiungi un connettore personalizzato con l’URL https://api.screenrig.ai/mcp e connettilo. Claude apre la pagina di consenso.

In Claude Code, aggiungi il server, poi autentica da /mcp:

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

Connetti ChatGPT

In ChatGPT, crea un’app (connettore) con l’URL server https://api.screenrig.ai/mcp e autenticazione OAuth. ChatGPT apre la pagina di consenso quando lo connetti. ChatGPT può anche iscriversi agli eventi, come uno schermo che va offline, e avvisarti quando accadono.

Connetti Grok

In Grok sul web, aggiungi un connettore personalizzato con l’URL server https://api.screenrig.ai/mcp. Quando chiede un client ID OAuth, inserisci screenrig-grok-web e lascia vuoto il client secret. Grok apre la pagina di consenso.

In Grok Build, aggiungi l’URL server come server HTTP remoto. Grok Build apre il browser per l’accesso la prima volta che usa il server.

Usa il server tramite API

Le API Claude, OpenAI e xAI si connettono a un server MCP remoto per ogni richiesta, con un valore di autorizzazione fornito. Usa un client di servizio: richiedi un token con resource=https://api.screenrig.ai/mcp, poi passalo con l’URL del server.

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 da quella richiesta funziona solo su /mcp, dura 15 minuti e agisce sul progetto del client di servizio con il suo livello di accesso e capacità. Richiedine uno nuovo quando scade.

Strumenti

Ogni nome strumento inizia con screenrig_. Le chiamate strumento eseguono gli stessi handler di CLI e REST API, con la stessa isolazione progetto, permessi, addebiti crediti, limiti di velocità, idempotenza e controlli revisione.

Come si comportano gli strumenti

• Impaginazione. Gli strumenti di elenco restituiscono una pagina, la più recente per prima (K/V in ordine di chiave). Passa un next_cursor non nullo come after, con gli stessi filtri, per la pagina successiva.
• Ritentativi. Le scritture accettano un idempotency_key opzionale. Riutilizzalo per ritentare la stessa scrittura in sicurezza; omettine uno per iniziare una nuova richiesta. Associazione, toast, screenshot, generazione immagini, inviti, link browser, cancellazioni operazioni e feedback ne richiedono uno, come indicato nei loro schemi di input.
• Revisioni. Le scritture accettano un revision opzionale. Una revisione obsoleta viene rifiutata: rileggi la risorsa, riapplica la modifica e ritenta.
• Revisioni. Gli strumenti di modifica di playlist e schermi accettano un review_note facoltativo, di al massimo 280 caratteri, che il revisore legge. Una modifica in attesa di revisione restituisce il corpo pending_review: di’ all’utente che attende la sua approvazione e dagli il url della revisione. Un media_update che cambia i tag di un media approvato restituisce l’elemento con review_state pending: gli schermi mantengono i tag approvati e la sua revisione compare in Revisioni entro pochi secondi. Un media_restore accetta lo stesso review_note e restituisce il corpo pending_review: il media continua a riprodurre il suo file finché una persona non approva.
• Cosa viene riprodotto. Uno schermo riproduce il livello più alto in vigore di uno stack: il suo takeover, le campagne che lo raggiungono (priority da 0 a 100, prima il valore più alto, poi la più recente), le voci della sua programmazione playlist in ordine e infine la sua playlist assegnata. Campagne e voci di programmazione accettano le stesse regole della CLI, tra cui monthly, dates, except e interaction. screen_get riporta effective_playlist con source takeover, campaign, schedule o default. schedule_calendar accetta from e to (al massimo 93 giorni di distanza) e uno tra screen_id, folder_id, tag o campaign_id: raggruppa gli schermi con stack identici ed elenca gli intervalli di ogni livello (plays, partial, outranked, conditional) e i conflitti (due campagne con la stessa priorità in vigore insieme, un livello che non viene mai riprodotto). Le scritture di campagna richiedono l’accesso Gestisci e non diventano mai revisioni: un’app Propose elenca solo gli strumenti di lettura delle campagne.
• Screenshots. screen_screenshot attende fino a 60 secondi e restituisce la cattura come contenuto immagine image/webp. screen_screenshot_current restituisce l’ultima immagine pronta e il suo tempo captured_at senza richiedere una nuova cattura.
• Regole di notifica. notification_create e notification_update accettano min_severity (info, warning o error), severity (da condizione a livello, ad esempio {"not_playing": "error"}), active_hours (timezone, windows e outside, hold o drop) e audience (le regole di un pubblico di campagna, al posto di screen_tags). reach_drop (screens, percent) stabilisce quanto deve essere ampio un calo della copertura di una campagna perché una condizione reach_dropped notifichi; è valido solo con quella condizione. reach_dropped e group_empty controllano le campagne, quindi screen_tags e audience non le limitano mai. In aggiornamento, null azzera ciascuno. Un avviso trattenuto o saltato compare in notification_deliveries.
• I segreti restano nascosti. I risultati webhook non includono mai il segreto di firma e riducono ogni URL destinatario alla sua origine. Gli inviti arrivano solo via email, quindi nessun link di invito raggiunge il modello.
• Revoca. project_credential_revoke disconnette l’agente la cui sessione ha effettuato la chiamata. Richiede confirmation: "REVOKE" e allow_last_agent: true per disconnettere l’ultimo agente attivo del progetto. Il progetto e i suoi contenuti restano. Un’app connessa termina la propria sessione tramite https://api.screenrig.ai/oauth/revoke, o una persona la disconnette nella pagina Accesso.
• Errori. Una chiamata rifiutata restituisce un errore strumento il cui contenuto strutturato è il documento problema dell’API REST, con code, detail e status. I metadati screenrig/result del risultato contengono http_status, e etag, credit_remaining o retry_after quando il server li ha inviati.

Risorse

Le risorse del progetto espongono metadati privati e non sono mai memorizzate nella cache. Il server fornisce anche una risorsa UI HTML per schede interattive negli host MCP Apps.

Eventi

Il server implementa MCP Events con consegna webhook. Un’app si iscrive a un evento, e screenRIG POSTa un messaggio firmato al callback HTTPS dell’app quando accade, così l’app può comunicare che uno schermo è offline o uno screenshot è pronto senza polling. L’iscrizione richiede una sessione OAuth: un’app connessa o un client di servizio. Le sessioni di sola lettura possono iscriversi, poiché gli eventi sono letture.

Un’app che propone modifiche impara ogni decisione da review.requested, review.approved, review.rejected e review.changes_requested.

I dati contengono solo ID e stati. Leggi il record completo con uno strumento, come screenrig_screen_get o screenrig_screen_screenshot_current.

Elenca e sottoscrivi

events/list restituisce gli eventi a cui questa sessione può iscriversi, ciascuno con un inputSchema e un payloadSchema. Gli eventi schermo accettano un argomento screenId opzionale per seguire uno schermo. events/subscribe prende l’evento, i suoi argomenti e la 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
  }
}

• Il segreto è tuo: whsec_ seguito da base64 di 24 a 64 byte casuali. Firma ogni consegna.
• Il callback è un URL HTTPS su un indirizzo pubblico, senza redirect.
• Il risultato include l’iscrizione id (sub_…), refreshBefore e cursor: null. Le consegne partono da ora; non c’è replay.
• Durata. ttlMs richiede da 5 minuti a 24 ore; il valore predefinito è un’ora, e null ottiene 24 ore. Rinnova con lo stesso nome, argomenti e URL prima di refreshBefore per estenderla; l’id resta lo stesso e il risultato riporta deliveryStatus. Un nuovo segreto su un aggiornamento firma insieme al vecchio per 10 minuti.
• Disiscrivi con events/unsubscribe e lo stesso nome, argomenti e delivery.url.

Un’organizzazione contiene fino a 100 sottoscrizioni in tutti i suoi progetti, e una sessione può sottoscriversi 120 volte all’ora. Una sottoscrizione termina quando la sua sessione o client servizio è revocato, la sua app disconnessa, la sua persona disattivata o il suo progetto eliminato, e la sua autorità si ricontrolla ogni 15 minuti.

Verifica il callback

La prima sottoscrizione da una sessione a un URL di callback invia un POST di verifica firmato:

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

Rispondi a 2xx entro 5 secondi con la stessa sfida in JSON:

{ "challenge": "RANDOM_CHALLENGE" }

Un controllo fallito risponde alla chiamata subscribe con errore JSON-RPC -32015, il cui data.reason è challenge_failed, timeout, connection_refused, tls_error, http_4xx o http_5xx.

Ricevi consegne

Ogni consegna è un POST di un solo evento, massimo 256 KiB:

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

Le consegne seguono Standard Webhooks:

Per verificare, decodifica il base64 dopo whsec_ nella chiave, calcola HMAC-SHA256 su webhook-id, ., webhook-timestamp, . e il corpo grezzo, e confronta il suo base64 con ogni valore v1, in tempo costante. Rifiuta un timestamp più di cinque minuti distante dal tuo orologio:

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

Rispondi a 2xx rapidamente. Una consegna fallita viene ritentata per 15 minuti; 410 Gone o 413 Payload Too Large la interrompono subito.

Usa la CLI per questi

Questi passaggi spostano file o segreti, o vengono eseguiti sulla tua macchina, quindi restano nel CLI incluso:

Correlato

• Avvia: installa il plugin ufficiale e la CLI inclusa.
• Autenticazione: sessioni, Solo lettura, Proponi e Gestisci, e la pagina Accesso.
• Clienti del servizio: token per server, script e connettori API.
• Riferimento CLI: ogni comando, con le stesse convenzioni degli strumenti sopra.
• Riferimento API: il contratto REST e i tipi di problema condivisi dagli strumenti.