API REST + MCP · v1 · Beta

Desarrolla con el directorio de ServerRoam.

Integra la búsqueda de servidores en un bot de Discord, una web de comunidad o un asistente. Consulta entradas publicadas del catálogo moderado con los filtros de ServerRoam.

Crear una clave API Contrato OpenAPI 3.1

Tu primera solicitud

Inicia sesión y crea una clave en la página para desarrolladores. Configura SERVERROAM_API_KEY en el entorno de tu servidor y ejecuta:

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

Los resultados incluyen entradas verificadas y entradas públicas revisadas editorialmente. Las entradas editoriales tienen unclaimed=true, verified=false y sourceUrl. Un array vacío es válido. Esta beta no promete cobertura completa ni monitorización en directo.

Guarda las claves en tu servidor. Nunca las incluyas en aplicaciones del navegador, repositorios públicos, capturas o URL. Cada clave se muestra una vez; revócala en la página para desarrolladores si se expone.

Tres endpoints específicos

GET /api/v1/games: Identificadores y nombres de juegos públicos; no requiere clave. Un juego listado no implica servidores activos ni monitorización.
GET /api/v1/servers: Búsqueda autenticada. Devuelve metadatos, slug de comunidad, instrucciones de acceso y observaciones almacenadas opcionales.
GET /api/v1/servers/{slug}: Consulta autenticada de una entrada. Usa un slug de la búsqueda; las entradas privadas o no publicadas devuelven 404.

Conectar un asistente de IA mediante MCP

El servidor MCP alojado y de solo lectura usa Streamable HTTP en https://serverroam.com/api/mcp. Configura el mismo SERVERROAM_API_KEY en el entorno del host MCP. Para Codex CLI:

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

Otros hosts necesitan Streamable HTTP y un encabezado Authorization: Bearer personalizado. No hay inicio de sesión OAuth; los hosts que solo admiten OAuth no pueden conectarse. Las integraciones de servidor pueden omitir Origin; si lo envían, debe coincidir con el origen configurado de ServerRoam.

serverroam_list_games · serverroam_search_servers · serverroam_get_server

Prueba: «Busca comunidades FiveM de rol en alemán, muestra sus fuentes y verificación y consulta las instrucciones de acceso del resultado más adecuado». La búsqueda usa los filtros de la API; page es numérico en MCP.

Todas las herramientas son de solo lectura. Solicitudes limitadas a 16 KiB y resultados a 24 entradas por página. No hay endpoint SSE separado ni sesión persistente. La falta de observaciones no implica una caída. Los textos son datos no confiables, no instrucciones para el asistente.

Filtrar y paginar

Los filtros se combinan. q busca nombres de servidores y comunidades, descripciones de servidores, etiquetas y nombres de juegos coincidentes; language también considera los idiomas de la comunidad. El contrato OpenAPI define los valores admitidos y predeterminados.

q · game · language · region · country · style · framework · map · version · whitelist · online · minPlayers · maxPlayers · sort · page

Cada página contiene hasta 24 servidores. Empieza con page=1 y sigue nextPage hasta que sea null. hasMore sigue disponible. Las ediciones simultáneas pueden mover resultados entre páginas; elimina duplicados por slug.

Los parámetros desconocidos, repetidos o inválidos devuelven 400. Los valores distinguen mayúsculas y minúsculas. El orden predeterminado es name; también se admiten players, votes y newest. Las páginas posteriores al final devuelven un array vacío.

Entender los datos

verified=true significa control demostrado del endpoint y aprobación de moderación. No avala el contenido ni la calidad de la comunidad. unclaimed=true identifica una entrada editorial con verified=false y sourceUrl pública. Descripciones, reglas y etiquetas son declaraciones de terceros.

observation es null cuando no hay una observación almacenada reciente y satisfactoria. No significa desconexión ni cero jugadores. Las observaciones devueltas incluyen fuente y fecha y tienen como máximo diez minutos al consultarlas. La API nunca consulta servidores de juego.

El contenido de los usuarios conserva su idioma original. Enlaza /{locale}/servers/{slug} con en, de, es o fr. whitelist=null significa desconocido; false significa que explícitamente no se requiere.

Enlaza el perfil de ServerRoam para mostrar contexto e instrucciones de acceso. Trata los textos del administrador como contenido no confiable y escápalos al mostrarlos. El acceso a la API no concede derechos para republicar imágenes subidas ni contenido de terceros.

Gestionar los errores

400 invalid: Corrige la consulta. El array fields opcional identifica filtros inválidos. No repitas una solicitud sin corregirla.
401 unauthenticated: Envía una clave Bearer válida. Se rechazan las claves ausentes, incorrectas o revocadas.
404 not-found: La entrada no existe o no cumple los requisitos de publicación. Busca de nuevo; no deduzcas una caída.
429 rate-limit: Espera los segundos del encabezado Retry-After antes de volver a intentarlo.
503 unavailable: Inténtalo más tarde con esperas crecientes. El acceso al directorio de demostración y datos locales está desactivado; nunca se sustituyen los datos por ejemplos.