Seguridad

GitLab MCP Server nunca almacena tu token de GitLab. En modo stdio lee el token de una variable de entorno al arrancar, lo mantiene solo en memoria durante la vida del proceso y lo envía únicamente a tu instancia de GitLab —por TLS cuando GITLAB_URL apunta a un endpoint https:// (el valor por defecto)— nunca a terceros. El modo solo lectura y el modo seguro (vistas previas en dry-run) añaden salvaguardas opcionales, y cada release incluye checksums y firmas para verificar su integridad. Esta página detalla ese 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 y nunca se incluye en las salidas de herramientas.
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_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx' > .env
# Añade GITLAB_URL aquí solo para instancias autogestionadas.

# 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_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

Filtrado de herramientas por scopes

Al iniciar, el servidor detecta los scopes de tu token mediante la API de GitLab y desactiva automáticamente las herramientas que requieren scopes que tu token no posee. Por ejemplo, un token sin el scope admin_mode no mostrará las herramientas gitlab_admin.

Esto evita que la IA intente operaciones que fallarían con errores de permisos y mantiene la lista de herramientas enfocada en lo que tu token puede hacer realmente.

Para desactivar la detección de scopes y registrar todas las herramientas independientemente de los permisos del token:

GITLAB_IGNORE_SCOPES=true

O en modo HTTP:

./gitlab-mcp-server --http --ignore-scopes

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
Configura --trusted-proxy-header con la cabecera que tu proxy establece (ej. Fly-Client-IP, X-Real-IP, X-Forwarded-For) para que el rate limiter integrado vea las IPs reales de los clientes. Habílita esto solo cuando el servidor sea accesible únicamente a través de un proxy de confianza que sobrescriba (o elimine las copias entrantes de) la cabecera configurada; de lo contrario los clientes pueden falsificarla y evadir el rate limiting por IP. Para X-Forwarded-For, el servidor usa la entrada más a la derecha — el último salto añadido por el proxy de confianza — para no confiar en valores suministrados por el cliente.
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/guides/oauth-app-setup.md para crear la Aplicación OAuth de GitLab requerida, y Modo servidor HTTP para los detalles completos de configuración.

Verificación de la integridad del release

Cada GitHub Release incluye dos artefactos de integridad:

checksums.txt — hashes SHA-256 de todos los binarios del release
checksums.txt.sigstore.json — bundle de firma keyless Cosign / Sigstore (GitHub OIDC, sin distribución de claves)

El mecanismo de auto-actualización verifica los binarios contra checksums.txt automáticamente antes de reemplazar el proceso en ejecución. Para instalaciones manuales, verifica tanto la firma como el checksum antes de ejecutar el binario.

1. Instalar Cosign

Sigue la guía oficial de instalación. Instalación rápida:

# macOS
brew install cosign

# Linux (binario de release)
curl -L https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64 -o cosign
chmod +x cosign && sudo mv cosign /usr/local/bin/

2. Descargar los artefactos del release

Desde la página de Releases, descarga:

El binario para tu plataforma (ej. gitlab-mcp-server-linux-amd64)
checksums.txt
checksums.txt.sigstore.json

3. Verificar la firma

cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp "^https://github.com/jmrplens/gitlab-mcp-server/" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  checksums.txt

Una verificación exitosa imprime Verified OK. La restricción --certificate-identity-regexp garantiza que la firma fue producida por un workflow de GitHub Actions ejecutado en este repositorio, y --certificate-oidc-issuer ancla la identidad al emisor OIDC oficial de GitHub.

4. Verificar el checksum del binario

Después de verificar la firma, valida que tu binario coincida con el checksum firmado:

# Linux
sha256sum --check --ignore-missing checksums.txt

# macOS (shasum no tiene --ignore-missing; filtra la línea relevante primero)
grep "$(ls gitlab-mcp-server-*)" checksums.txt | shasum -a 256 -c

Salida esperada: gitlab-mcp-server-linux-amd64: OK (o el nombre de archivo correspondiente para tu plataforma).

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)
☐ Verifica la firma Cosign/Sigstore en la primera instalación manual (instrucciones arriba)
☐ Bloqueo de esquema: todos los esquemas de entrada de herramientas aplican additionalProperties: false para rechazar campos inesperados

Modo HTTP

☐ Despliega detrás de un proxy inverso con terminación TLS
☐ Configura --trusted-proxy-header para un rate limiting preciso
☐ 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

Preguntas frecuentes

¿Cómo protege GitLab MCP Server mi token en modo stdio?

En modo stdio el token de GitLab nunca sale del proceso local del servidor. Se carga desde el entorno y se usa exclusivamente para llamadas a la API de GitLab —nunca se envía al cliente MCP ni se incluye en las salidas de herramientas. El servidor se ejecuta como proceso local comunicándose por stdin/stdout, así que no se abren puertos de red, y solo necesita un token con los scopes requeridos para las operaciones que pretendas usar.

¿Qué scopes de token debería usar?

Usa los scopes mínimos para tu flujo: read_api para operaciones de solo lectura, api para operaciones completas de crear/actualizar/eliminar, y read_repository o write_repository para acceso o modificación de archivos del repositorio. Si solo necesitas operaciones de lectura, usa read_api y habilita además GITLAB_READ_ONLY=true como defensa en profundidad. Al iniciar, el servidor detecta los scopes de tu token y desactiva las herramientas que requieren scopes que el token no posee.

¿Cuál es la diferencia entre el modo solo lectura y el modo seguro?

El modo solo lectura (GITLAB_READ_ONLY=true) no registra ninguna herramienta de escritura, así que solo están disponibles list, get y search —una garantía firme a nivel de servidor. El modo seguro (GITLAB_SAFE_MODE=true) sí registra las herramientas de escritura pero las intercepta y devuelve una vista previa JSON estructurada del nombre, los parámetros y las anotaciones en lugar de ejecutarlas. Si ambos están activos, el modo solo lectura tiene precedencia y las herramientas de escritura se desactivan por completo.

¿Cómo verifico la integridad de un binario descargado?

Cada GitHub Release incluye checksums.txt (hashes SHA-256) y checksums.txt.sigstore.json (un bundle de firma keyless Cosign/Sigstore con GitHub OIDC). La auto-actualización verifica los binarios contra checksums.txt automáticamente. Para instalaciones manuales, ejecuta cosign verify-blob con el bundle, anclando la identidad del certificado a este repositorio y el emisor OIDC a GitHub, y luego valida el hash del binario contra el checksum firmado. Si la verificación falla, no ejecutes el binario.

Referencias externas

Scopes de tokens de acceso personal de GitLab — elegir scopes de mínimo privilegio
OAuth 2.0 Protected Resource Metadata (RFC 9728) — el estándar detrás del modo OAuth por HTTP
Documentación de Sigstore / Cosign — verificación de firmas keyless de los binarios de release

Mantenido por José Manuel Requena PlensGitHub LinkedIn Mastodon Google Scholar