API und MCP

gibeon.io lässt sich vollständig per Code steuern, sobald du ein Access-Token hast. Die REST-API liegt unter www.gibeon.io/v1. Für KI-Tools, die MCP sprechen (Claude Desktop, Claude Code, Cursor), steht derselbe Satz an Aktionen unter www.gibeon.io/mcp bereit. Eine lokale Installation ist nicht nötig.

Du willst nur Claude verbinden, ohne Code? Dann folge Claude mit gibeon.io verbinden.

Ein funktionierendes Beispiel vom Token bis zur Veröffentlichung findest du in den Quickstarts für Python, Node.js und Go.

Was du damit machen kannst

Mit einem einzigen Access-Token arbeitest du direkt in deiner Organisation:

• Bildschirme auflisten, umbenennen, anderen Inhalt zuweisen, eine Veröffentlichung auslösen
• Playlists erstellen, Einträge hinzufügen oder entfernen, die Reihenfolge ändern
• Sequenzen und Planungen verwalten
• Assets hochladen und abrufen

Die vollständige interaktive Referenz findest du unter www.gibeon.io/dev/reference. Die rohe OpenAPI-3.1-Spezifikation ist unter www.gibeon.io/v1/openapi.yaml erreichbar und eignet sich für Codegenerierung oder den Import in Postman, Bruno, Insomnia.

Ein Access-Token abrufen

Die Authentifizierung läuft über OAuth 2.1, Authorization Code + PKCE, ausgegeben von Supabase. Es gibt keine statischen Schlüssel mehr zum Kopieren.

1. Dein Client registriert sich per Dynamic Client Registration (RFC 7591) beim Authorization Server
2. Der Client durchläuft den Authorization-Code-Flow mit PKCE
3. Du genehmigst den Zugriff auf dem Zustimmungsbildschirm von gibeon.io und wählst die Organisation, in der der Agent arbeiten darf (Scope gibeon:api)
4. Dein Client erhält ein kurzlebiges Access-Token plus ein Refresh-Token

Den vollständigen Flow mit jedem Endpoint findest du unter www.gibeon.io/auth.md. Für Headless- oder Cron-Nutzung bewahrst du das Refresh-Token auf und tauschst es gegen neue Access-Tokens ein, ohne erneut genehmigen zu müssen (einmalig von einem Menschen eingerichtet).

Den Zugriff widerrufst du im CMS unter Einstellungen → Verbundene Apps oder über den Revocation-Endpoint des Authorization Servers. Das Widerrufen wirkt sofort.

REST verwenden

Sende das Access-Token im Authorization-Header als Bearer-Token mit.

# Liste deiner Bildschirme
curl https://www.gibeon.io/v1/players \
  -H "Authorization: Bearer <access_token>"

# Einen Bildschirm auf eine andere Playlist setzen und veröffentlichen
curl -X PATCH https://www.gibeon.io/v1/players/<player_id> \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "playlist_id": "<playlist_id>" }'

curl -X POST https://www.gibeon.io/v1/players/<player_id>/publish \
  -H "Authorization: Bearer <access_token>"

Funktioniert mit jeder Sprache, die HTTPS spricht: bash, Node, Python, Go, n8n, Zapier, Make.

MCP verwenden: gehostet (empfohlen)

Füge diese Konfiguration in die MCP-Einstellungen deines KI-Tools ein. Der Client autorisiert sich bei der ersten Verbindung selbst per OAuth: Er bekommt ein 401 mit einem WWW-Authenticate-Verweis, ruft die Protected-Resource-Metadaten ab, registriert sich selbst (DCR) und durchläuft den OAuth-Flow. Du genehmigst den Zustimmungsbildschirm einmal. In der Konfiguration steht also kein Token.

{
  "mcpServers": {
    "gibeon": {
      "url": "https://www.gibeon.io/mcp"
    }
  }
}

Speicherort der Konfiguration je Tool:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) oder das Pendant unter Windows/Linux
• Claude Code: .mcp.json in deinem Projekt oder die globale Konfiguration über claude mcp
• Cursor: ~/.cursor/mcp.json

Nach einem Neustart des Tools erscheinen 14 gibeon.io-Tools (list_players, update_player, publish_players, create_player, create_playlist, add_playlist_item, reorder_playlist_items, …). Die KI kann sie direkt aufrufen.

MCP verwenden: npm-Paket (deprecated)

Es gab eine selbst gehostete stdio-Variante (@gibeon/mcp-server), aber sie wurde abgebaut (deprecated): Die Variante verwendete die entfernten gib_live_-Schlüssel. Nutze das gehostete MCP oben, das die Autorisierung bei der ersten Verbindung selbst übernimmt.

Limits und gutes Verhalten

• 60 Requests pro Minute pro Token. Über dem Limit gibt die API 429 mit einem Retry-After-Header in Sekunden zurück.
• Tokens sind auf die Organisation beschränkt. Ein Token kann nie über die genehmigte Organisation hinausschauen, auch nicht bei einem Superadmin-Konto.
• Veröffentlichungen sind kostenlos, was Rate-Limit und Kosten betrifft. Du darfst nach jeder Änderung eine Veröffentlichung auslösen. Ein Bildschirm mit aktiver Verbindung bekommt sofort einen Hinweis und lädt die neue Version innerhalb weniger Sekunden; eine Playlist wechselt erst beim nächsten Eintrag. Muss nur ein Bildschirm geändert werden, veröffentliche nur diesen Bildschirm: Eine Veröffentlichung für alle Bildschirme startet die Wiedergabe auf jedem Zonen- und Sequenz-Bildschirm neu.
• Assets hochladen geht in zwei Schritten: zuerst POST /v1/assets mit Metadaten (du bekommst eine Upload-URL zurück), dann PUT der Bytes an diese URL. Maximal 100 MB pro Upload.

Häufige Fehler