Verbinden Sie einen MCP-Client mit Ihren Bildschirmen

Der Server

Der Server speichert keine Sitzungen. Er lehnt GET, DELETE, Mcp-Session-Id und Cookies ab. Jede Anfrage authentifiziert sich selbst, sodass eine getrennte App beim nächsten Aufruf nicht mehr funktioniert. Anfragen sind auf 4 MiB begrenzt.

Das offizielle Plugin übernimmt den gesamten Workflow: Es lädt Dateien hoch und packt Anwendungen auf Ihrem Rechner. Verwenden Sie den MCP-Server, wenn Ihr Client Werkzeuge über MCP aufruft, und behalten Sie die gebündelte CLI für die lokale Arbeit.

Mit OAuth verbinden

MCP-Clients finden die Anmeldung selbst. Eine Anfrage ohne Token antwortet mit 401 und WWW-Authenticate: Bearer resource_metadata="https://api.screenrig.ai/.well-known/oauth-protected-resource/mcp", und dieses Dokument nennt den Autorisierungsserver, https://api.screenrig.ai. Seine Metadaten sind unter https://api.screenrig.ai/.well-known/oauth-authorization-server zu finden.

1. Fügen Sie die Server-URL zu Ihrem Client hinzu. Der Client öffnet die screenRIG-Zustimmungsseite in Ihrem Browser.
2. Melden Sie sich bei Bedarf am Dashboard an. Die Seite zeigt den Namen und die Domain der App an, wie sie von der App deklariert werden, ob screenRIG sie registriert hat und wohin Ihr Browser zurückkehrt.
3. Wählen Sie das Projekt, Nur Lesen, Vorschlagen oder Verwalten sowie die Berechtigungen, dann wählen Sie App verbinden und bestätigen mit Ihrem Passkey.
4. Ihr Browser kehrt zur App zurück, die jetzt eine eigene Sitzung hat. Diese erneuert die Sitzung selbst; jeder Zugriffstoken ist 15 Minuten gültig.

Verbinden Sie nur eine App, die Sie gerade selbst einrichten. Clients identifizieren sich mit einem Client-ID-Metadaten-Dokument (CIMD), daher gibt es keinen Registrierungsschritt. Die Autorisierung verwendet PKCE mit S256, exakten Redirect-URIs und einem einmal verwendbaren Code, der 60 Sekunden gültig ist.

Die App erscheint unter Verbundene Apps auf der Zugriff-Seite des Dashboards. Trennen dort beendet sie innerhalb von Sekunden; erneutes Verbinden ermöglicht die Auswahl eines anderen Projekts oder Zugriffslevels. Siehe Authentifizierung für die dahinterliegenden Sitzungen.

Der CLI- und MCP-Host führen separate Sitzungen. Kopieren Sie das gespeicherte CLI-Token nicht in die MCP-Konfiguration, fügen Sie keine Anmeldedaten in ein Gespräch ein und übergeben Sie sie nicht an eine eingebettete Karte. Der Host verwaltet seine OAuth-Tokens und deren Aktualisierung selbst.

Das offizielle Plugin fordert access:manage, screens, content, playlists und reports an; der Benutzer genehmigt den Zugriff während der Anmeldung. Ein frischer Screenshot erfordert Propose- oder Manage-Zugriff und die screens-Fähigkeit. Eine bestehende schreibgeschützte Verbindung benötigt vor der Anforderung einer Aufnahme eine erneute Zustimmung.

MCP-Apps-Hosts können interaktive Bildschirm-, Medien- und Playlist-Karten über die authentifizierte Verbindung rendern. Die Karte verwendet die MCP-Apps-Brücke des Hosts; sie enthält keine Zugangsdaten und ruft die API nicht direkt auf. Hosts ohne MCP-Apps-Rendering können weiterhin Tooltexte und strukturierte Daten verwenden.

Nur lesen, vorschlagen und verwalten

Verbundene Apps sind standardmäßig auf Nur lesen eingestellt. Eine Nur-Lesen-App listet nur Lesewerkzeuge auf, und der Aufruf eines Werkzeugs über das Sitzungsniveau antwortet mit HTTP 403 insufficient_access mit WWW-Authenticate: Bearer error="insufficient_scope" und dem scope, der dies erlaubt. Webhook-Empfänger-URLs werden für Nur lesen als geschwärzt angezeigt.

Eine Propose-App listet auch die Werkzeuge auf, die hochladen, annotieren und vorschlagen. Ihre Playlist- und Bildschirmänderungen geben status: "pending_review" mit der Überprüfung id und url zurück, anstatt sie anzuwenden, und eine Person genehmigt sie im Dashboard unter Reviews. Wenn das Projekt eine Überprüfung für Agentenänderungen verlangt, arbeitet jede App höchstens im Propose-Modus. Um der App direkte Änderungen zu erlauben, trennen Sie sie und verbinden Sie sie erneut mit Manage.

tools/list gibt nur die Werkzeuge zurück, die das Zugriffslevel und die Fähigkeiten der Sitzung erlauben. Die Planberechtigungen des Projekts gelten zusätzlich, genau wie bei der CLI. Jeder Werkzeugaufruf ist eine Agentenanfrage, die wie jede andere abgerechnet wird.

Claude verbinden

Fügen Sie in Claude (Web, Desktop oder Mobil) einen benutzerdefinierten Connector mit der URL https://api.screenrig.ai/mcp hinzu und verbinden Sie ihn. Claude öffnet die Zustimmungsseite.

Fügen Sie in Claude Code den Server hinzu und authentifizieren Sie sich dann von /mcp aus:

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

ChatGPT verbinden

Erstellen Sie in ChatGPT eine App (Connector) mit der Server-URL https://api.screenrig.ai/mcp und OAuth-Authentifizierung. ChatGPT öffnet die Zustimmungsseite, wenn Sie es verbinden. ChatGPT kann auch Events abonnieren, wie z. B. wenn ein Bildschirm offline geht, und Sie benachrichtigen, wenn dies geschieht.

Grok verbinden

Fügen Sie in Grok im Web einen benutzerdefinierten Connector mit der Server-URL https://api.screenrig.ai/mcp hinzu. Wenn nach einer OAuth-Client-ID gefragt wird, geben Sie screenrig-grok-web ein und lassen Sie das Client-Geheimnis leer. Grok öffnet die Zustimmungsseite.

Fügen Sie in Grok Build die Server-URL als Remote-HTTP-Server hinzu. Grok Build öffnet beim ersten Serverzugriff die Browser-Anmeldeseite.

Verwenden Sie den Server über eine API

Die Claude-, OpenAI- und xAI-APIs verbinden sich pro Anfrage mit einem entfernten MCP-Server, mit einem von Ihnen bereitgestellten Autorisierungswert. Verwenden Sie einen Service-Client: Fordern Sie ein Token mit resource=https://api.screenrig.ai/mcp an und übergeben Sie es zusammen mit der Server-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

Ein Token aus dieser Anfrage funktioniert nur auf /mcp, ist 15 Minuten gültig und wirkt auf das Projekt des Service-Clients mit dessen Zugriffslevel und Fähigkeiten. Fordern Sie ein neues an, wenn es abläuft.

Werkzeuge

Jeder Werkzeugname beginnt mit screenrig_. Werkzeugaufrufe führen dieselben Handler wie CLI und REST API aus, mit derselben Projektisolation, Berechtigungen, Kreditbelastungen, Ratenbegrenzungen, Idempotenz- und Revisionsprüfungen.

Wie sich die Werkzeuge verhalten

• Paging. Listenwerkzeuge geben eine Seite zurück, neueste zuerst (K/V in Schlüsselreihenfolge). Übergeben Sie ein nicht-null next_cursor zurück als after mit denselben Filtern für die nächste Seite.
• Wiederholungen. Schreibvorgänge akzeptieren optional ein idempotency_key. Verwenden Sie es erneut, um denselben Schreibvorgang sicher zu wiederholen; lassen Sie es weg, um eine neue Anfrage zu starten. Pairing, Toasts, Screenshots, Bildgenerierung, Einladungen, Browser-Links, Abbruch von Operationen und Feedback erfordern eines, und ihre Eingabeschemata geben dies an.
• Revisionen. Schreibvorgänge akzeptieren optional ein revision. Eine veraltete Revision wird abgelehnt: Lesen Sie die Ressource erneut, wenden Sie die Änderung erneut an und versuchen Sie es erneut.
• Überprüfungen. Die Werkzeuge für Playlist- und Bildschirmänderungen akzeptieren ein optionales review_note mit höchstens 280 Zeichen, das der Prüfer liest. Eine Änderung, die auf Überprüfung wartet, liefert den Body pending_review: Teilen Sie dem Benutzer mit, dass sie auf seine Freigabe wartet, und nennen Sie ihm die url der Überprüfung. Ein media_update, der die Tags freigegebener Medien ändert, liefert das Element mit review_state pending: Bildschirme behalten die freigegebenen Tags, und die Überprüfung erscheint innerhalb weniger Sekunden unter Überprüfungen. Ein media_restore akzeptiert dasselbe review_note und liefert den Body pending_review: Das Medium spielt seine Datei weiter ab, bis eine Person freigibt.
• Was abgespielt wird. Ein Bildschirm spielt die oberste geltende Ebene eines Stapels ab: seine Übernahme, die Kampagnen, die ihn erreichen (priority 0 bis 100, höhere zuerst, dann die neueste), seine Playlist-Zeitplaneinträge der Reihe nach, dann seine zugewiesene Playlist. Kampagnen und Zeitplaneinträge nehmen dieselben Regeln wie die CLI entgegen, darunter monthly, dates, except und interaction. screen_get meldet effective_playlist mit source takeover, campaign, schedule oder default. schedule_calendar nimmt from und to (höchstens 93 Tage auseinander) und eines von screen_id, folder_id, tag oder campaign_id: Es gruppiert Bildschirme mit identischen Stapeln und listet die Zeitspannen jeder Ebene (plays, partial, outranked, conditional) und die Konflikte (zwei Kampagnen gleicher Priorität, die gleichzeitig gelten, eine Ebene, die nie abgespielt wird). Schreibvorgänge an Kampagnen erfordern Manage-Zugriff und werden nie zu Überprüfungen: Eine Propose-App listet nur die Lesewerkzeuge für Kampagnen auf.
• Screenshots. screen_screenshot wartet bis zu 60 Sekunden und liefert die Aufnahme als image/webp Bildinhalt zurück. screen_screenshot_current gibt das zuletzt fertige Standbild und dessen captured_at Zeit zurück, ohne eine neue Aufnahme anzufordern.
• Benachrichtigungsregeln. notification_create und notification_update akzeptieren min_severity (info, warning oder error), severity (Bedingung zu Schweregrad, etwa {"not_playing": "error"}), active_hours (timezone, windows und outside, hold oder drop) und audience (die Regeln einer Kampagnen-Zielgruppe statt screen_tags). reach_drop (screens, percent) legt fest, wie groß ein Rückgang der Reichweite einer Kampagne sein muss, damit eine reach_dropped-Bedingung eine Meldung sendet; sie ist nur mit dieser Bedingung gültig. reach_dropped und group_empty überwachen Kampagnen, daher schränken screen_tags und audience sie nie ein. Beim Aktualisieren löscht null jeweils den Wert. Eine zurückgehaltene oder übersprungene Meldung erscheint in notification_deliveries.
• Geheimnisse bleiben außen vor. Webhook-Ergebnisse enthalten niemals das Signaturgeheimnis und reduzieren jede Empfänger-URL auf ihren Ursprung. Einladungen erfolgen nur per E-Mail, sodass kein Einladungslink das Modell erreicht.
• Widerrufen. project_credential_revoke trennt den Agenten, dessen Sitzung den Aufruf gemacht hat. Es erfordert confirmation: "REVOKE" und allow_last_agent: true, um den letzten aktiven Agenten des Projekts zu trennen. Das Projekt und seine Inhalte bleiben erhalten. Eine verbundene App beendet ihre eigene Sitzung über https://api.screenrig.ai/oauth/revoke, oder eine Person trennt sie auf der Zugriffsseite.
• Fehler. Ein abgelehnter Aufruf gibt einen Tool-Fehler zurück, dessen strukturierter Inhalt das Problem-Dokument der REST-API ist, mit code, detail und status. Die Metadaten des Ergebnisses screenrig/result enthalten http_status sowie etag, credit_remaining oder retry_after, wenn der Server diese gesendet hat.

Ressourcen

Projektressourcen geben private Metadaten preis und werden niemals zwischengespeichert. Der Server stellt auch eine HTML-Benutzeroberflächenressource für interaktive Karten in MCP Apps-Hosts bereit.

Ereignisse

Der Server implementiert MCP-Ereignisse mit Webhook-Zustellung. Eine App abonniert ein Ereignis, und screenRIG sendet eine signierte Nachricht an den HTTPS-Rückruf der App, wenn es passiert, sodass die App Ihnen mitteilen kann, dass ein Bildschirm offline ging oder ein Screenshot bereitsteht, ohne zu pollieren. Das Abonnieren benötigt eine OAuth-Sitzung: eine verbundene App oder einen Service-Client. Nur-Lese-Sitzungen können abonnieren, da Ereignisse Lesevorgänge sind.

Eine App, die Änderungen vorschlägt, lernt jede Entscheidung von review.requested, review.approved, review.rejected und review.changes_requested.

Daten enthalten nur IDs und Zustände. Lesen Sie den vollständigen Datensatz mit einem Tool, wie screenrig_screen_get oder screenrig_screen_screenshot_current.

Auflisten und abonnieren

events/list gibt die Ereignisse zurück, die diese Sitzung abonnieren darf, jeweils mit einem inputSchema und einem payloadSchema. Bildschirmevents nehmen ein optionales screenId-Argument, um einem Bildschirm zu folgen. events/subscribe nimmt das Ereignis, seine Argumente und den Callback entgegen:

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

• Das Geheimnis gehört Ihnen: whsec_ gefolgt von Base64 von 24 bis 64 zufälligen Bytes. Es signiert jede Lieferung.
• Der Callback ist eine HTTPS-URL an einer öffentlichen Adresse, ohne Weiterleitungen.
• Das Ergebnis enthält das Abonnement id (sub_…), refreshBefore und cursor: null. Lieferungen beginnen ab jetzt; es gibt keine Wiederholung.
• Lebensdauer. ttlMs verlangt 5 Minuten bis 24 Stunden; der Standard ist eine Stunde, und null erhält 24 Stunden. Abonnieren Sie vor refreshBefore erneut mit demselben Namen, denselben Argumenten und URL, um es zu verlängern; die ID bleibt gleich, und das Ergebnis meldet deliveryStatus. Ein neues Geheimnis bei einer Aktualisierung wird 10 Minuten lang neben dem alten signiert.
• Abbestellen mit events/unsubscribe und demselben Namen, Argumenten und delivery.url.

Eine Organisation enthält bis zu 100 Abonnements über alle ihre Projekte, und eine Sitzung kann sich 120 Mal pro Stunde abonnieren. Ein Abonnement endet, wenn seine Sitzung oder sein Service-Client widerrufen wird, seine App getrennt wird, seine Person deaktiviert wird oder sein Projekt gelöscht wird, und seine Berechtigung wird alle 15 Minuten erneut geprüft.

Callback verifizieren

Das erste Abonnement von einer Sitzung zu einer Callback-URL sendet einen signierten Verifizierungs-POST:

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

Antworten Sie 2xx innerhalb von 5 Sekunden mit derselben Herausforderung als JSON:

{ "challenge": "RANDOM_CHALLENGE" }

Eine fehlgeschlagene Prüfung antwortet auf den Subscribe-Aufruf mit JSON-RPC-Fehler -32015, dessen data.reason challenge_failed, timeout, connection_refused, tls_error , http_4xx oder http_5xx ist.

Lieferungen empfangen

Jede Zustellung ist ein POST eines Ereignisses, maximal 256 KiB:

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

Zustellungen folgen Standard-Webhooks:

Zur Überprüfung dekodieren Sie das Base64 nach whsec_ in den Schlüssel, berechnen HMAC-SHA256 über webhook-id, ., webhook-timestamp, . und den Rohkörper und vergleichen dessen Base64 mit jedem v1,-Wert in konstanter Zeit. Lehnen Sie einen Zeitstempel ab, der mehr als fünf Minuten von Ihrer Uhr abweicht:

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

Antworten Sie 2xx schnell. Eine fehlgeschlagene Zustellung wird 15 Minuten lang erneut versucht; 410 Gone oder 413 Payload Too Large stoppt sie sofort.

Verwenden Sie die CLI für diese

Diese Schritte verschieben Dateien oder Geheimnisse oder laufen auf Ihrem Gerät, sodass sie in der gebündelten CLI bleiben:

Verwandt

• Starten: Installieren Sie das offizielle Plugin und die gebündelte CLI.
• Authentifizierung: Sitzungen, Nur lesen, Vorschlagen und Verwalten sowie die Zugriffsseite.
• Service-Clients: Tokens für Server, Skripte und API-Connectoren.
• CLI-Referenz: alle Befehle mit denselben Konventionen wie die oben genannten Tools.
• API-Referenz: der REST-Vertrag und die gemeinsam genutzten Problemtypen der Tools.