Seguridad

GitLab MCP Server está diseñado con una arquitectura que prioriza la seguridad. Esta página cubre el modelo de seguridad, el manejo de credenciales y las mejores prácticas para un despliegue seguro.

Descripción general del modelo de seguridad

flowchart TB
    subgraph Local["Máquina Local"]
        Token["Token de GitLab<br/>(variable de entorno / archivo .env)"]
        Server["Proceso del Servidor MCP"]
        Client["Cliente MCP<br/>(VS Code, etc.)"]
    end
    subgraph Remote["Red"]
        GitLab["Instancia de GitLab"]
    end

    Token --> Server
    Client <-->|"stdio (stdin/stdout)"| Server
    Server <-->|"HTTPS"| GitLab

Principios clave

Aislamiento del token: En modo stdio, el token de GitLab nunca sale del proceso local del servidor. Se carga desde el entorno y se utiliza exclusivamente para llamadas a la API de GitLab.
Sin reenvío de tokens: El token nunca se envía al cliente MCP, nunca se incluye en las salidas de herramientas y nunca se pasa a través de solicitudes de sampling MCP.
Aislamiento a nivel de proceso: El servidor se ejecuta como un proceso local comunicándose a través de stdin/stdout. No se abren puertos de red en modo stdio.
Mínimo privilegio: El servidor solo necesita un token de GitLab con los scopes requeridos para las operaciones que deseas utilizar.

Gestión de tokens

Recomendado: Archivo de entorno

Almacena tu token en un archivo .env con permisos restringidos:

# Crear archivo .env
echo 'GITLAB_URL=https://gitlab.example.com' > .env
echo 'GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx' >> .env

# Restringir permisos (solo lectura/escritura del propietario)
chmod 600 .env

Variables de entrada en VS Code

Para usuarios de VS Code, puedes usar variables de entrada para evitar almacenar tokens en texto plano:

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "gitlab-mcp-server",
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "${input:gitlabToken}"
      }
    }
  }
}

El token se solicita al inicio y se mantiene solo en memoria.

Scopes del token

Usa los scopes mínimos requeridos para tu flujo de trabajo:

Scope	Requerido Para
`read_api`	Operaciones de solo lectura (listar, obtener, buscar)
`api`	Operaciones completas (crear, actualizar, eliminar)
`read_repository`	Acceso a archivos del repositorio
`write_repository`	Modificación de archivos del repositorio

Eliminación de credenciales en sampling

Cuando las herramientas de análisis usan sampling MCP para enviar datos al LLM del cliente, el servidor aplica eliminación automática de credenciales antes de que cualquier dato salga del proceso. Esta es una medida crítica de defensa en profundidad que previene la fuga accidental de tokens a través del contexto del LLM.

Patrones eliminados

El motor de eliminación de credenciales usa patrones regex para detectar y eliminar:

Patrón	Ejemplo	Reemplazo
PAT de GitLab	`glpat-aBcDeFgH12345678`	`[REDACTED:GITLAB_TOKEN]`
Token de Pipeline de GitLab	`glptt-aBcDeFgH12345678`	`[REDACTED:GITLAB_TOKEN]`
Clave de Acceso AWS	`AKIAIOSFODNN7EXAMPLE`	`[REDACTED:AWS_KEY]`
Clave Secreta AWS	`wJalrXUtnFEMI/K7MDENG/...`	`[REDACTED:AWS_SECRET]`
Token de Slack	`xoxb-...` / `xoxp-...`	`[REDACTED:SLACK_TOKEN]`
Webhook de Slack	`hooks.slack.com/services/...`	`[REDACTED:SLACK_WEBHOOK]`
JWT	`eyJhbGciOi...`	`[REDACTED:JWT]`
Clave API genérica	`api_key=...`, `apikey: ...`	`[REDACTED:API_KEY]`
Clave SSH privada	`-----BEGIN RSA PRIVATE KEY-----`	`[REDACTED:PRIVATE_KEY]`

Verificación TLS

Por defecto, el servidor verifica los certificados TLS al conectarse a GitLab. Para certificados autofirmados:

GITLAB_SKIP_TLS_VERIFY=true

Modo de solo lectura

Habilita el modo de solo lectura para prevenir cualquier operación de escritura:

GITLAB_READ_ONLY=true

En modo de solo lectura:

Todas las herramientas de escritura no se registran (crear, actualizar, eliminar, fusionar, etc.)
Solo las operaciones de lectura están disponibles (listar, obtener, buscar)
Esto proporciona una garantía firme a nivel de servidor — el LLM no puede modificar datos accidentalmente

Esto es útil para:

Flujos de trabajo de exploración y descubrimiento
Entornos de demostración
Entornos donde el token tiene acceso de escritura pero deseas restringir el servidor

Modo seguro

Habilita el modo seguro para previsualizar operaciones de escritura sin ejecutarlas:

GITLAB_SAFE_MODE=true

En modo seguro:

Las herramientas de escritura devuelven una vista previa JSON estructurada mostrando nombre de herramienta, parámetros y anotaciones
Las herramientas de solo lectura se ejecutan normalmente
Si GITLAB_READ_ONLY=true también está configurado, tiene precedencia (las herramientas de escritura se desactivan completamente)

Esto es útil para flujos de trabajo dry-run, entornos de formación y depuración de parámetros de herramientas.

Seguridad en modo HTTP

Al ejecutar en modo HTTP (--http), aplican consideraciones de seguridad adicionales:

Autenticación por solicitud

En modo HTTP, los tokens de GitLab se proporcionan por solicitud a través de cabeceras, no de variables de entorno. Cada sesión de usuario usa su propio token:

Authorization: Bearer <gitlab-personal-access-token>

Aislamiento de sesiones

El servidor mantiene un pool LRU limitado de sesiones de cliente:

Cada token obtiene su propia instancia aislada del servidor MCP
Las sesiones son independientes — un usuario no puede acceder al contexto de otro
Las sesiones inactivas expiran después de --session-timeout (por defecto: 30 minutos)
El máximo de sesiones concurrentes se controla con --max-http-clients (por defecto: 100)

Recomendaciones para modo HTTP

Despliega detrás de un proxy inverso con terminación TLS
Habilita limitación de velocidad a nivel del proxy
Restringe el acceso a redes de confianza
Monitoriza las métricas de sesiones para detectar patrones inusuales

Modo OAuth

Para despliegues HTTP en producción, considera usar el modo OAuth (--auth-mode=oauth). Habilita autenticación OAuth 2.1 compatible con RFC 9728:

Los usuarios autorizan a través del navegador — no es necesario distribuir tokens manualmente
OAuth 2.1 con PKCE protege contra la interceptación del código de autorización
La identidad del token se cachea durante --oauth-cache-ttl (por defecto: 15 minutos, rango: 1m–2h)
La cabecera PRIVATE-TOKEN sigue siendo compatible para retrocompatibilidad

Consulta docs/oauth-app-setup.md para crear la Aplicación OAuth de GitLab requerida, y Modo Servidor HTTP para los detalles completos de configuración.

Lista de verificación de mejores prácticas

Seguridad del token

☐ Usa un token de GitLab dedicado con los scopes mínimos requeridos
☐ Almacena tokens en archivos .env con permisos chmod 600
☐ Añade .env al .gitignore
☐ Rota los tokens periódicamente
☐ Usa el scope read_api cuando no se necesita acceso de escritura

Configuración del servidor

☐ Habilita GITLAB_READ_ONLY=true para flujos de trabajo de solo lectura
☐ Mantén la verificación TLS habilitada (GITLAB_SKIP_TLS_VERIFY sin establecer o false)
☐ Usa transporte stdio cuando sea posible (sin exposición de red)
☐ Mantén el binario del servidor actualizado (AUTO_UPDATE=true)

Modo HTTP

☐ Despliega detrás de un proxy inverso con terminación TLS
☐ Configura apropiadamente --session-timeout y --max-http-clients
☐ Habilita limitación de velocidad
☐ Restringe el acceso de red a clientes de confianza

Monitorización

☐ Revisa los logs del servidor regularmente
☐ Monitoriza patrones inusuales de llamadas a la API
☐ Verifica la expiración del token o cambios de permisos
☐ Habilita LOG_LEVEL=info para registros de auditoría en producción