Registro de Logs

GitLab MCP Server utiliza registro dual — los mensajes de log se envían tanto a stderr (para captura en terminal/archivo) como al cliente MCP a través de la capacidad de logging del protocolo.

Salida dual

flowchart LR
    A[Llamada a herramienta] --> B[Logger]
    B --> C[stderr<br/>Texto legible / JSON]
    B --> D[MCP notifications/message<br/>Interfaz del cliente]

    style A fill:#6366f1,color:#fff
    style B fill:#8b5cf6,color:#fff
    style C fill:#3b82f6,color:#fff
    style D fill:#22c55e,color:#fff

Destino	Formato	Propósito
stderr	Texto legible o JSON	Salida de terminal, redirección a archivo, depuración
Protocolo MCP	`notifications/message`	Mostrado en la interfaz del cliente MCP (por ejemplo, panel de salida de VS Code)

Esto garantiza que los logs siempre sean visibles independientemente del soporte de logging del cliente.

Niveles de log

Niveles de stderr (`LOG_LEVEL`)

La variable de entorno LOG_LEVEL acepta cuatro valores:

Nivel	Cuándo se Usa
debug	Información de diagnóstico detallada — parámetros de llamadas a herramientas, detalles de peticiones/respuestas API, operaciones del pool de sesiones
info	Eventos operativos normales — inicio del servidor, registro de herramientas, comprobaciones de actualización
warn	Problemas no fatales — tiempos de espera de red, configuración opcional faltante, uso obsoleto
error	Fallos — errores de autenticación, fallos de API, errores irrecuperables de herramientas

Niveles del protocolo MCP (RFC 5424)

Las notificaciones MCP notifications/message soportan los ocho niveles de severidad RFC 5424. Los clientes pueden filtrar mediante logging/setLevel:

Nivel	Severidad	Cuándo se Usa
debug	Mínima	Detalles de diagnóstico (parámetros de herramientas, trazas API)
info		Eventos normales (inicio, registro)
notice		Condiciones significativas pero normales
warning		Problemas potenciales (timeouts, deprecaciones)
error		Fallos en operaciones (errores API, fallos de autenticación)
critical		Condiciones críticas que requieren atención inmediata
alert		Se debe actuar inmediatamente
emergency	Máxima	El sistema no es utilizable

Configuración

Establece el nivel de log mediante variable de entorno:

# Modo stdio
LOG_LEVEL=debug ./gitlab-mcp-server

# Modo HTTP
LOG_LEVEL=info ./gitlab-mcp-server --http --gitlab-url=https://gitlab.com

El nivel predeterminado es info.

Mensajes de log MCP

Cuando el cliente MCP soporta logging, el servidor envía notificaciones de log estructuradas:

{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "info",
    "logger": "gitlab-mcp-server",
    "data": {
      "message": "starting MCP server",
      "transport": "stdio",
      "version": "x.y.z",
      "tools": 32,
      "resources": 46,
      "prompts": 38
    }
  }
}

Los conteos de este ejemplo representan la configuración activa en tiempo de ejecución y pueden variar según la superficie de herramientas, la superficie de capacidades y el gating Enterprise/Premium.

Reglas de seguridad

Los mensajes de log siguen reglas estrictas de seguridad:

Sin tokens — Los tokens de GitLab nunca se incluyen en los mensajes de log
Identificadores enmascarados — En modo HTTP, los tokens se muestran como ...a1b2 (solo los últimos 4 caracteres)
Sin PII — Los datos enviados por el usuario no se registran en nivel info o superior
Solo debug — Los datos detallados de petición/respuesta solo se registran en nivel debug