Connecter un client MCP à vos écrans

Le serveur

Le serveur ne conserve aucune session. Il refuse GET, DELETE, Mcp-Session-Id et les cookies. Chaque requête s’authentifie seule, donc une application déconnectée cesse de fonctionner à son prochain appel. Les requêtes sont limitées à 4 Mio.

Le plugin officiel couvre tout le flux de travail : il téléverse les fichiers et emballe les applications sur votre machine. Utilisez le serveur MCP lorsque votre client appelle des outils via MCP, et conservez le CLI intégré pour le travail local.

Connecter avec OAuth

Les clients MCP trouvent la connexion par eux-mêmes. Une requête sans jeton répond 401 avec WWW-Authenticate: Bearer resource_metadata="https://api.screenrig.ai/.well-known/oauth-protected-resource/mcp", et ce document nomme le serveur d’autorisation, https://api.screenrig.ai. Ses métadonnées sont à https://api.screenrig.ai/.well-known/oauth-authorization-server.

1. Ajouter l’URL du serveur à votre client. Le client ouvre la page de consentement screenRIG dans votre navigateur.
2. Connectez-vous au tableau de bord si nécessaire. La page affiche le nom et le domaine de l’application tels que déclarés, que screenRIG l’ait enregistrée ou non, et où votre navigateur revient.
3. Choisissez le projet, Lecture seule, Proposer ou Gérer, ainsi que les capacités, puis choisissez Connecter l’app et confirmez avec votre clé d’accès.
4. Votre navigateur revient à l’application, qui a maintenant sa propre session. Elle renouvelle cette session elle-même ; chaque jeton d’accès dure 15 minutes.

Connectez uniquement une application que vous configurez vous-même, maintenant. Les clients s’identifient avec un Document de métadonnées d’ID client (CIMD), donc il n’y a pas d’étape d’enregistrement. L’autorisation utilise PKCE avec S256, des URI de redirection exacts et un code à usage unique valable 60 secondes.

L’application apparaît sous Applications connectées dans la page Accès du tableau de bord. Déconnecter y met fin en quelques secondes ; reconnectez-la pour choisir un projet ou un niveau d’accès différent. Voir Authentification pour les sessions associées.

Le CLI et l’hôte MCP gardent des sessions séparées. Ne copiez pas le jeton sauvegardé du CLI dans la configuration MCP, ne collez pas les identifiants dans une conversation, ni ne les transmettez à une carte intégrée. L’hôte gère ses propres jetons OAuth et leur actualisation.

Le plugin officiel demande access:manage, screens, content, playlists et reports ; l’utilisateur approuve l’accès lors de la connexion. Une capture d’écran fraîche nécessite un accès Proposer ou Gérer et la capacité screens. Une connexion existante en lecture seule requiert un consentement renouvelé avant de demander une capture.

Les hôtes MCP Apps peuvent rendre des cartes interactives d’écran, média et liste de lecture via la connexion authentifiée. La carte utilise le pont MCP Apps de l’hôte ; elle ne contient aucune information d’identification et n’appelle pas l’API directement. Les hôtes sans rendu MCP Apps peuvent toujours consommer le texte d’outil et les données structurées.

Lecture seule, proposer et gérer

Les applications connectées sont par défaut en Lecture seule. Une application en Lecture seule liste uniquement les outils de lecture, et appeler un outil au-delà du niveau de session répond par HTTP 403 insufficient_access avec WWW-Authenticate: Bearer error="insufficient_scope" et le scope qui l’autorise. Les URL des récepteurs webhook sont masquées en Lecture seule.

Une app Propose liste aussi les outils qui téléversent, annotent et proposent. Ses changements de liste de lecture et d’écran retournent status: "pending_review" avec la revue id et url au lieu d’appliquer, et une personne les approuve dans le Revue du tableau de bord. Quand le projet exige une revue pour les changements d’agent, toutes les apps fonctionnent au plus à Propose. Pour laisser l’app faire des changements directement, déconnectez-la puis reconnectez-la avec Manage.

tools/list retourne uniquement les outils que le niveau d’accès et les capacités de la session permettent. Les droits du forfait du projet s’appliquent en plus, exactement comme pour le CLI. Chaque appel d’outil est une requête d’agent, facturée comme toute autre.

Connecter Claude

Dans Claude (web, bureau ou mobile), ajoutez un connecteur personnalisé avec l’URL https://api.screenrig.ai/mcp et connectez-le. Claude ouvre la page de consentement.

Dans Claude Code, ajoutez le serveur, puis authentifiez-vous depuis /mcp :

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

Connecter ChatGPT

Dans ChatGPT, créez une app (connecteur) avec l’URL du serveur https://api.screenrig.ai/mcp et une authentification OAuth. ChatGPT ouvre la page de consentement lorsque vous le connectez. ChatGPT peut aussi s’abonner aux événements, comme un écran hors ligne, et vous informer lorsqu’ils se produisent.

Connecter Grok

Dans Grok sur le web, ajoutez un connecteur personnalisé avec l’URL du serveur https://api.screenrig.ai/mcp. Lorsqu’il demande un ID client OAuth, entrez screenrig-grok-web et laissez le secret client vide. Grok ouvre la page de consentement.

Dans Grok Build, ajoutez l’URL du serveur comme serveur HTTP distant. Grok Build ouvre la connexion du navigateur la première fois qu’il utilise le serveur.

Utilisez le serveur via une API

Les API Claude, OpenAI et xAI se connectent à un serveur MCP distant par requête, avec une valeur d’autorisation que vous fournissez. Utilisez un client de service : demandez un jeton avec resource=https://api.screenrig.ai/mcp, puis transmettez-le avec l’URL du serveur.

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 jeton issu de cette requête ne fonctionne que sur /mcp, dure 15 minutes et agit sur le projet du client de service avec son niveau d’accès et ses capacités. Demandez-en un nouveau à son expiration.

Outils

Chaque nom d’outil commence par screenrig_. Les appels d’outil exécutent les mêmes gestionnaires que le CLI et l’API REST, avec la même isolation de projet, autorisations, frais de crédits, limites de débit, idempotence et vérifications de révision.

Comment les outils se comportent

• Pagination. Les outils de liste retournent une page, la plus récente en premier (K/V dans l’ordre des clés). Renvoyez un next_cursor non nul comme after, avec les mêmes filtres, pour la page suivante.
• Nouvelles tentatives. Les écritures acceptent un idempotency_key optionnel. Réutilisez-le pour retenter la même écriture en toute sécurité ; omettez-le pour démarrer une nouvelle requête. Le jumelage, les notifications toast, les captures d’écran, la génération d’images, les invitations, les liens de navigateur, les annulations d’opération et les retours d’information en requièrent un, et leurs schémas d’entrée l’indiquent.
• Révisions. Les écritures acceptent un revision optionnel. Une révision périmée est refusée : relisez la ressource, réappliquez la modification et retentez.
• Révisions. Les outils de modification de playlist et d’écran acceptent un review_note facultatif, de 280 caractères au plus, que le réviseur lit. Une modification qui attend une révision renvoie le corps pending_review : dites à l’utilisateur qu’elle attend son approbation et donnez-lui le url de la révision. Un media_update qui change les étiquettes d’un média approuvé renvoie l’élément avec review_state pending : les écrans gardent ses étiquettes approuvées, et sa révision apparaît dans Révisions en quelques secondes. Un media_restore accepte le même review_note et renvoie le corps pending_review : le média continue de diffuser son fichier jusqu’à ce qu’une personne approuve.
• Ce qui joue. Un écran joue le niveau le plus haut qui est en vigueur dans une pile : sa prise de contrôle, les campagnes qui l’atteignent (priority de 0 à 100, la plus élevée d’abord, puis la plus récente), les entrées de son horaire de liste de lecture dans l’ordre, puis sa liste de lecture assignée. Les campagnes et les entrées d’horaire acceptent les mêmes règles que le CLI, dont monthly, dates, except et interaction. screen_get rapporte effective_playlist avec source takeover, campaign, schedule ou default. schedule_calendar prend from et to (au plus 93 jours d’écart) et l’un de screen_id, folder_id, tag ou campaign_id : il regroupe les écrans à piles identiques et liste les plages de chaque niveau (plays, partial, outranked, conditional) et les conflits (deux campagnes de même priorité en vigueur en même temps, un niveau qui ne joue jamais). Les écritures de campagne nécessitent l’accès Gérer et ne deviennent jamais des révisions : une app Propose ne liste que les outils de lecture des campagnes.
• Captures d’écran. screen_screenshot attend jusqu’à 60 secondes et renvoie la capture comme contenu d’image image/webp. screen_screenshot_current renvoie la dernière image fixe prête et son temps captured_at sans demander une nouvelle capture.
• Règles de notification. notification_create et notification_update acceptent min_severity (info, warning ou error), severity (condition vers niveau, comme {"not_playing": "error"}), active_hours (timezone, windows et outside, hold ou drop) et audience (les règles d’une audience de campagne, au lieu de screen_tags). reach_drop (screens, percent) fixe l’ampleur d’une baisse de la portée d’une campagne qui déclenche un avis pour une condition reach_dropped ; il n’est valide qu’avec cette condition. reach_dropped et group_empty surveillent des campagnes, donc screen_tags et audience ne les limitent jamais. Lors d’une mise à jour, null efface chacun. Un avis mis en attente ou ignoré apparaît dans notification_deliveries.
• Les secrets restent à l’écart. Les résultats du webhook ne contiennent jamais le secret de signature et réduisent chaque URL de récepteur à son origine. Les invitations se font uniquement par courriel, donc aucun lien d’invitation n’atteint le modèle.
• Révocation. project_credential_revoke déconnecte l’agent dont la session a effectué l’appel. Cela requiert confirmation: "REVOKE", et allow_last_agent: true pour déconnecter le dernier agent actif du projet. Le projet et son contenu restent. Une application connectée termine sa propre session via https://api.screenrig.ai/oauth/revoke, ou une personne la déconnecte sur la page Accès.
• Erreurs. Un appel refusé renvoie une erreur d’outil dont le contenu structuré est le document de problème de l’API REST, avec code, detail et status. Les métadonnées screenrig/result du résultat portent http_status, et etag, credit_remaining ou retry_after lorsque le serveur les a envoyées.

Ressources

Les ressources du projet exposent des métadonnées privées et ne sont jamais mises en cache. Le serveur fournit aussi une ressource UI HTML pour les cartes interactives dans les hôtes MCP Apps.

Événements

Le serveur implémente MCP Events avec livraison webhook. Une application s’abonne à un événement, et screenRIG POSTe un message signé au rappel HTTPS de l’application quand il se produit, pour que l’application puisse vous dire qu’un écran est hors ligne ou qu’une capture d’écran est prête sans sondage. L’abonnement nécessite une session OAuth : une application connectée ou un client de service. Les sessions en lecture seule peuvent s’abonner, car les événements sont des lectures.

Une app qui propose des changements apprend chaque décision de review.requested, review.approved, review.rejected et review.changes_requested.

Les données ne contiennent que les identifiants et états. Lisez l’enregistrement complet avec un outil, tel que screenrig_screen_get ou screenrig_screen_screenshot_current.

Lister et s’abonner

events/list retourne les événements auxquels cette session peut s’abonner, chacun avec un inputSchema et un payloadSchema. Les événements d’écran prennent un argument screenId optionnel pour suivre un écran. events/subscribe prend l’événement, ses arguments et le rappel :

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

• Le secret est à vous : whsec_ suivi de base64 de 24 à 64 octets aléatoires. Il signe chaque livraison.
• Le rappel est une URL HTTPS sur une adresse publique, sans redirections.
• Le résultat porte l’abonnement id (sub_…), refreshBefore et cursor: null. Les livraisons commencent maintenant ; il n’y a pas de relecture.
• Durée de vie. ttlMs demande de 5 minutes à 24 heures ; la valeur par défaut est une heure, et null obtient 24 heures. Abonnez-vous à nouveau avec le même nom, arguments et URL avant refreshBefore pour prolonger ; l’ID reste le même, et le résultat indique deliveryStatus. Un nouveau secret lors d’un rafraîchissement signe avec l’ancien pendant 10 minutes.
• Désabonnez-vous avec events/unsubscribe et le même nom, arguments et delivery.url.

Une organisation contient jusqu’à 100 abonnements, tous projets confondus, et une session peut s’abonner 120 fois par heure. Un abonnement se termine lorsque sa session ou son client de service est révoqué, son application est déconnectée, sa personne est désactivée ou son projet est supprimé, et son autorité est vérifiée toutes les 15 minutes.

Vérifier le rappel

La première souscription d’une session à une URL de rappel envoie un POST de vérification signé :

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

Répondez à 2xx dans les 5 secondes avec le même défi au format JSON :

{ "challenge": "RANDOM_CHALLENGE" }

Une vérification échouée répond à l’appel subscribe avec une erreur JSON-RPC -32015, dont le data.reason est challenge_failed, timeout, connection_refused, tls_error, http_4xx ou http_5xx.

Recevoir les livraisons

Chaque livraison correspond à un POST d’un seul événement, d’au plus 256 KiB :

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

Les livraisons suivent les Webhooks Standard :

Pour vérifier, décodez le base64 après whsec_ dans la clé, calculez le HMAC-SHA256 sur webhook-id, ., webhook-timestamp, . et le corps brut, puis comparez son base64 avec chaque valeur v1, en temps constant. Rejetez un horodatage à plus de cinq minutes de votre horloge :

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

Répondez à 2xx rapidement. Une livraison échouée est retentée pendant 15 minutes ; 410 Gone ou 413 Payload Too Large l’arrête immédiatement.

Utilisez le CLI pour ceux-ci

Ces étapes déplacent des fichiers ou des secrets, ou s’exécutent sur votre machine, donc elles restent dans le CLI intégré :

Lié

• Démarrer : installez le plugin officiel et son CLI inclus.
• Authentification : sessions, lecture seule, proposer et gérer, et la page d’accès.
• Clients du service : jetons pour serveurs, scripts et connecteurs API.
• Référence CLI : chaque commande, avec les mêmes conventions que les outils ci-dessus.
• Référence API : le contrat REST et les types de problèmes partagés par les outils.