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": 33,
      "resources": 46,
      "prompts": 37
    }
  }
}

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