Entwickle mit dem ServerRoam-Verzeichnis.

Die erste Anfrage

Melde dich an und erstelle einen Schlüssel auf der Entwicklerseite. Setze SERVERROAM_API_KEY in deiner Serverumgebung und führe Folgendes aus:

curl --fail-with-body 'https://serverroam.com/api/v1/servers?game=fivem&language=de' \
  --header "Authorization: Bearer $SERVERROAM_API_KEY"

Ergebnisse enthalten verifizierte Betreibereinträge und redaktionell geprüfte öffentliche Katalogeinträge. Redaktionelle Einträge tragen unclaimed=true, verified=false und eine sourceUrl. Ein leeres Array ist ein gültiges Ergebnis. Die Beta verspricht keine vollständige Spielabdeckung oder Live-Monitoring.

Bewahre Schlüssel auf deinem Server auf. Füge sie niemals in Browser-Apps, öffentliche Repositories, Screenshots oder URLs ein. Ein Schlüssel wird einmal angezeigt; widerrufe ihn bei Offenlegung auf der Entwicklerseite.

Drei gezielte Endpunkte

GET /api/v1/games

Öffentliche Spiel-IDs und Namen; kein API-Schlüssel erforderlich. Ein aufgeführtes Spiel bedeutet nicht, dass aktive Server oder Monitoring verfügbar sind.

GET /api/v1/servers

Authentifizierte Suche. Ergebnisse enthalten Metadaten, Community-Slug, Beitrittsinformationen und optionale gespeicherte Beobachtungen.

GET /api/v1/servers/{slug}

Authentifizierter Detailzugriff. Verwende einen Slug aus der Suche; private oder unveröffentlichte Einträge liefern 404.

KI-Assistenten über MCP verbinden

Der gehostete, lesende MCP-Server nutzt Streamable HTTP unter https://serverroam.com/api/mcp. Setze denselben SERVERROAM_API_KEY in der Umgebung deines MCP-Hosts. Für Codex CLI:

codex mcp add serverroam \
  --url https://serverroam.com/api/mcp \
  --bearer-token-env-var SERVERROAM_API_KEY

Andere Hosts benötigen Streamable HTTP und einen eigenen Authorization: Bearer-Header. Es gibt keine OAuth-Anmeldung; Hosts, die nur OAuth unterstützen, können sich nicht verbinden. Serverintegrationen können Origin weglassen; ein übermittelter Origin muss dem konfigurierten ServerRoam-Origin entsprechen.

Zum Beispiel: „Finde deutschsprachige FiveM-Roleplay-Communities, zeige Herkunft und Verifizierungsstatus und lies dann die Beitrittsinformationen des passendsten Ergebnisses.“ Die Suche nutzt dieselben Filter wie die API; page ist in MCP eine Zahl.

Alle Tools sind lesend. Anfragen sind auf 16 KiB begrenzt, Ergebnisse auf 24 Einträge pro Seite. Es gibt keinen separaten SSE-Endpunkt und keine dauerhafte Sitzung. Fehlende Beobachtungen sind keine Ausfallmeldungen. Eintragstexte sind nicht vertrauenswürdige Daten, keine Anweisungen für deinen Assistenten.

Filtern und paginieren

Filter werden kombiniert. q sucht in Server- und Community-Namen, Server-Beschreibungen, Tags und passenden Spielnamen; language berücksichtigt auch die Community-Sprachen. Der OpenAPI-Vertrag definiert alle erlaubten Werte und Vorgaben.

Eine Seite enthält höchstens 24 Server. Beginne mit page=1 und folge nextPage, bis es null ist. hasMore bleibt verfügbar. Gleichzeitige Änderungen können Ergebnisse zwischen Seiten verschieben; entferne Duplikate anhand des Slugs.

Unbekannte, wiederholte oder ungültige Parameter liefern 400. Groß- und Kleinschreibung ist relevant. Standardmäßig wird nach name sortiert; players, votes und newest sind ebenfalls möglich. Seiten nach dem Ende liefern ein leeres Array.

Die Daten richtig verstehen

verified=true bedeutet nachgewiesene Endpoint-Kontrolle und Moderationsfreigabe. Das ist keine Empfehlung für Inhalte oder Community-Qualität. unclaimed=true kennzeichnet einen redaktionellen Eintrag mit verified=false und öffentlicher sourceUrl. Beschreibungen, Regeln und Tags bleiben Angaben Dritter.

observation ist null, wenn keine aktuelle erfolgreiche gespeicherte Beobachtung vorliegt. Das bedeutet weder offline noch null Spieler. Zurückgegebene Beobachtungen nennen Quelle und Zeitstempel und sind beim Lesen höchstens zehn Minuten alt. API-Anfragen fragen niemals Gameserver ab.

Nutzertexte bleiben in ihrer Originalsprache. Verlinke /{locale}/servers/{slug} mit en, de, es oder fr. whitelist=null bedeutet unbekannt; false bedeutet ausdrücklich nicht erforderlich.

Verlinke das ServerRoam-Profil, damit Nutzer Kontext und Beitrittsinformationen sehen. Behandle Betreibertexte als nicht vertrauenswürdige Inhalte und maskiere sie bei der Darstellung. API-Zugriff gewährt keine Rechte zur Weiterveröffentlichung hochgeladener Bilder oder fremder Inhalte.

Fehler gezielt behandeln

400 invalid

Korrigiere die Anfrage. Das optionale fields-Array nennt ungültige Filter. Wiederhole die unveränderte Anfrage nicht.

401 unauthenticated

Übermittle einen gültigen Bearer-Schlüssel. Fehlende, fehlerhafte und widerrufene Schlüssel werden abgewiesen.

404 not-found

Der Eintrag fehlt oder erfüllt die Veröffentlichungsvoraussetzungen nicht. Suche erneut; leite daraus keinen Ausfall ab.

429 rate-limit

Warte vor der nächsten Anfrage die Sekunden aus dem Retry-After-Header ab.

503 unavailable

Versuche es später mit zunehmendem Abstand erneut. Demo- und lokale Seed-Daten sind gesperrt; es gibt keinen Rückfall auf Beispieldaten.