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

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 ~/.gitlab-mcp-server.env con permisos restringidos:

# Crear el archivo de entorno en el home
echo 'GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx' > ~/.gitlab-mcp-server.env
# Añade GITLAB_URL aquí solo para instancias autogestionadas.

# Restringir permisos (solo lectura/escritura del propietario)
chmod 600 ~/.gitlab-mcp-server.env

Para guardar el archivo en otro sitio, nómbralo por ruta absoluta en GITLAB_MCP_ENV_FILE.

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_MCP_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_MCP_SKIP_TLS_VERIFY=true

En modo HTTP, --auth-mode=oauth rechaza --skip-tls-verify para una instancia que no sea loopback: los tokens bearer se reenvían a esa instancia en cada llamada, y un certificado sin verificar permitiría a cualquier host que respondiera en su dirección recogerlos. En su lugar, instala la CA en el almacén de confianza del sistema o apunta SSL_CERT_FILE a un bundle de CA.

Modo de solo lectura

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

GITLAB_MCP_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_MCP_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_MCP_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 entradas por credencial:

Cada par de token y URL de GitLab obtiene su propia entrada aislada: su cliente de GitLab, su cubo del rate limit, sus vigilantes de recursos y sus sesiones. El servidor MCP y su catálogo de herramientas los comparten todas las credenciales de la misma configuración, porque ninguno depende de la credencial, y cada petición se ejecuta con el cliente que lleva su propia entrada
Las credenciales son independientes — un usuario no puede acceder al contexto de otro, ni a su estado de vigilancia, ni a la existencia de su tráfico
Las sesiones inactivas expiran después de --session-timeout (por defecto: 30 minutos) con --stateless=false; el transporte sin estado por defecto termina la sesión de cada POST con su respuesta
Las entradas del pool están acotadas por --max-http-clients (por defecto: 100), que limita entradas token+URL, no sesiones ni peticiones concurrentes. Bajo ese límite el desalojo prefiere una entrada que no esté atendiendo una suscripción, y se lleva una ocupada solo cuando todas las entradas del pool lo están; a la credencial desalojada se le avisa en lugar de dejarla muda

Recomendaciones para modo HTTP

Termina TLS en un proxy inverso, o en el propio servidor con --tls-cert/--tls-key; si el proxy comparte máquina, --http-addr=/run/…/server.sock elimina el salto en lugar de cifrarlo
Configura --trusted-proxy-header con la cabecera que tu proxy establece (ej. CF-Connecting-IP, X-Real-IP, X-Forwarded-For) junto con --trusted-proxies, las direcciones o rangos CIDR desde los que conecta el proxy, para que el limitador de fallos de autenticación (diez fallos por dirección y minuto, respondidos con 429) cargue a las direcciones reales de los clientes y no a la del proxy; el limitador de tasa por llamada se indexa por token y no necesita ninguna dirección. La cabecera solo se cree en una conexión que venga de una dirección de la lista; desde cualquier otro origen se ignora y se carga al propio origen, así que un cliente que llegue al listener directamente no puede elegir la dirección a la que se cargan sus fallos. Una opción sin la otra impide el arranque. Para X-Forwarded-For, el servidor lee desde la derecha, saltando los saltos que están a su vez en la lista, y carga al primero que no lo esté; un salto que no sea una dirección carga al origen de la conexión.
Habilita la limitación de peticiones en el 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), con clave hash SHA-256 — los tokens en claro nunca se almacenan
Los scopes concedidos se introspeccionan desde GitLab en lugar de asumirse
El modo OAuth es solo Bearer: PRIVATE-TOKEN se rechaza con 401. Los clientes sin soporte OAuth envían un token de acceso personal como Authorization: Bearer <glpat-...>, que se verifica igual
La admisión solo exige read_api, lo mínimo que necesita cualquier acción; que una llamada pueda escribir se decide acción por acción, contra la superficie construida para ese token. Por eso un despliegue que escribe acepta también un token read_api, y le sirve la superficie de solo lectura: la única credencial que se rechaza en la puerta es la que no lleva ningún scope de la API de GitLab. El desafío y scopes_supported nombran el único scope que da la superficie completa (api, o read_api con --read-only o --safe-mode), nunca los dos: un cliente pide a GitLab todos los scopes que aparecen, y GitLab rechaza una petición que nombra un scope que la aplicación OAuth no tiene. Un cliente que quiera una credencial incapaz de modificar nada pide read_api por su cuenta
Los rechazos son baratos y acotados: diez fallos de autenticación desde una misma dirección en un minuto se responden con 429, y un token que GitLab ya rechazó se rechaza desde memoria durante cinco minutos en lugar de volver a preguntar. Ni una caída ni un 429 de GitLab se cachean nunca — no dicen nada sobre la credencial
Un GitLab saturado o inalcanzable responde 503 con Retry-After y sin desafío, no 401. Reportarlo como token inválido haría que un cliente correcto descartase una credencial buena y arrancase un flujo de autorización nuevo, añadiendo carga justo cuando la instancia pedía menos

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.

Protección cross-origin

Las peticiones no seguras (POST, DELETE) que un navegador hace desde otro origen se rechazan con 403 antes de la autenticación, cumpliendo el requisito del transporte 2026-07-28 de validar Origin frente a DNS rebinding. Los clientes que no son navegador —CLIs, IDEs y SDKs— no envían Origin ni Sec-Fetch-Site y no se ven afectados, y los métodos seguros (server card, /health, metadatos OAuth) están exentos.

Para permitir clientes de navegador desde orígenes concretos, decláralos explícitamente:

gitlab-mcp-server --http --trusted-origins=https://mcp.example.com

Una lista blanca es validación: todo origen que no esté en ella se sigue rechazando. Una IP a secas sirve para despliegues locales, * acepta cualquier origen (desactivando la protección — solo razonable en una red de confianza o tras un proxy del mismo origen), y el origen de --public-url es de confianza automáticamente. Una entrada malformada impide arrancar.

Si un proxy inverso delante ya anuncia CORS en nombre del servidor —la forma con la que arrancaron casi todos los despliegues—, ese bloque tiene que salir en el mismo cambio. Dos cabeceras Access-Control-Allow-Origin son un fallo de CORS, no una fusión: curl responde 200 y el navegador rechaza la respuesta diciendo que la cabecera «contiene múltiples valores… y solo se permite uno». Dejar las dos deja el endpoint peor que antes, porque el * solitario del proxy al menos servía para peticiones sin credenciales.

Permitir el origen es solo la mitad de lo que necesita un navegador. Antes de enviar un POST cross-origin con Authorization, envía un preflight OPTIONS sin credenciales — que el modo OAuth rechazaba con 401, así que la petición real nunca llegaba a salir. Un preflight desde un origen de confianza se responde ahora con 204 y las cabeceras CORS, y la respuesta expone Mcp-Session-Id y Mcp-Protocol-Version para que un navegador pueda leerlas. El origen se devuelve tal cual en lugar de responder *, porque un navegador rechaza el comodín en una petición con credenciales.

Verificación de la integridad del release

Cada GitHub Release incluye tres 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)
<artefacto>.sbom.json — un SBOM en formato SPDX por cada binario

Nada de esto se verifica por ti: el servidor nunca descarga ni reemplaza su propio binario, así que quien pone un binario en la máquina es quien lo comprueba. Los gestores de paquetes hacen su propia verificación (Homebrew fija una fórmula con checksums; npm y el registro de contenedores fijan digests). Para un binario que descargues tú, verifica tanto la firma como el checksum antes de ejecutarlo.

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).

5. Verificar la procedencia de compilación (opcional)

Cada artefacto del release lleva una atestación de procedencia SLSA guardada por GitHub, que liga el fichero a la ejecución de workflow que lo produjo:

gh attestation verify gitlab-mcp-server-linux-amd64 -R jmrplens/gitlab-mcp-server

Es independiente de la firma Cosign: la firma dice que los checksums vienen del pipeline de release de este repositorio; la atestación dice qué ejecución construyó exactamente este fichero.

6. Verificar la imagen de contenedor

La imagen se publica en dos registros, y a ambos se sube el mismo índice, así que el digest es idéntico y cualquiera de las dos referencias verifica el mismo artefacto:

# Firma: quién subió este índice. Cualquiera de los dos registros, misma respuesta.
cosign verify ghcr.io/jmrplens/gitlab-mcp-server:3.0.0 \
  --certificate-identity-regexp "^https://github.com/jmrplens/gitlab-mcp-server/" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

cosign verify docker.io/jmrplens/gitlab-mcp-server:3.0.0 \
  --certificate-identity-regexp "^https://github.com/jmrplens/gitlab-mcp-server/" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

# Procedencia de compilación: qué commit y qué ejecución de workflow la produjeron
gh attestation verify oci://ghcr.io/jmrplens/gitlab-mcp-server:3.0.0 -R jmrplens/gitlab-mcp-server
gh attestation verify oci://docker.io/jmrplens/gitlab-mcp-server:3.0.0 -R jmrplens/gitlab-mcp-server

Los dos comandos responden preguntas distintas y ninguno sustituye al otro. La firma liga el índice a la identidad del workflow de release; su predicado está vacío, así que dice quién subió la imagen y no qué entró en ella. La atestación de procedencia nombra el commit de origen y la ejecución del workflow.

La imagen lleva además una atestación de SBOM sobre el índice y sobre cada manifiesto de plataforma, de modo que tanto un escáner que resuelve una etiqueta como uno que resuelve la plataforma que ejecuta encuentran un documento. El tipo de predicado es https://spdx.dev/Document sin versión, que es la forma con la que comparan los escáneres:

# SBOM: qué hay dentro de la imagen. Una etiqueta resuelve al índice, que lleva uno.
gh attestation verify oci://ghcr.io/jmrplens/gitlab-mcp-server:3.0.0 -R jmrplens/gitlab-mcp-server \
  --predicate-type https://spdx.dev/Document

# O por el digest del manifiesto de plataforma que realmente ejecutas
digest=$(docker buildx imagetools inspect ghcr.io/jmrplens/gitlab-mcp-server:3.0.0 \
  --format '{{range .Manifest.Manifests}}{{if and .Platform (eq .Platform.Architecture "amd64")}}{{.Digest}}{{end}}{{end}}')
gh attestation verify "oci://ghcr.io/jmrplens/gitlab-mcp-server@${digest}" -R jmrplens/gitlab-mcp-server \
  --predicate-type https://spdx.dev/Document

Cada uno de esos documentos se adjunta una segunda vez como referrer application/spdx+json en crudo, porque lo que escribe la atestación es un bundle de sigstore y un lector que busca el propio tipo de medio SPDX no lo reconoce. Ambos aparecen juntos:

oras discover --format tree ghcr.io/jmrplens/gitlab-mcp-server:3.0.0

¿El token aparece en los logs?

El servidor no registra el token. El logging de llamadas a herramientas es estructurado y escribe un conjunto fijo de campos en stderr: el nombre de la herramienta, la duración de la llamada, el error cuando lo hay y, si la petición lleva una identidad autenticada, el nombre de usuario y el ID de GitLab con fines de auditoría. El token no es uno de esos campos, y se envía a GitLab como cabecera de la petición y no en la URL, así que tampoco aparece en las rutas registradas.

Dos matices que conviene decir con claridad. Primero, los logs de cualquier nivel contienen la URL de GitLab, las rutas de proyecto y los identificadores de recursos sobre los que operas, y GITLAB_MCP_LOG_LEVEL=debug añade más detalle de ese tipo: trátalos como cualquier otro log operativo. Segundo, el servidor no puede controlar lo que tu cliente MCP registre en su propia transcripción. Si encuentras una credencial en la salida del servidor, repórtalo por el canal indicado abajo.

Reportar una vulnerabilidad

Reporta los problemas de seguridad de forma privada mediante GitHub Security Advisories, que mantiene el reporte confidencial hasta que se publique una corrección coordinada. No abras un issue público para una vulnerabilidad de seguridad.

Un reporte útil incluye la versión afectada (gitlab-mcp-server --version), el transporte en uso (stdio o HTTP), los pasos para reproducirlo y el impacto que crees que tiene. Si GitHub Security Advisories no está disponible para ti, contacta con el mantenedor en privado en GitHub (@jmrplens) en lugar de por un canal público. La política completa, con las versiones soportadas y los idiomas preferidos, está en SECURITY.md.

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 ~/.gitlab-mcp-server.env con permisos chmod 600
☐ Mantén fuera del control de versiones cualquier archivo que contenga un token
☐ Rota los tokens periódicamente
☐ Usa el scope read_api cuando no se necesita acceso de escritura

Configuración del servidor

☐ Habilita GITLAB_MCP_READ_ONLY=true para flujos de trabajo de solo lectura
☐ Mantén la verificación TLS habilitada (GITLAB_MCP_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 por el canal con el que lo instalaste
☐ 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

☐ Termina TLS — proxy inverso, --tls-cert/--tls-key, o un socket unix hacia un proxy del mismo host
☐ Configura --trusted-proxy-header y --trusted-proxies para que los fallos de autenticación se carguen a las direcciones reales de los clientes
☐ Configura apropiadamente --session-timeout y --max-http-clients
☐ Habilita la limitación de peticiones
☐ 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 GITLAB_MCP_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: al iniciar, el servidor detecta los scopes de tu token, sirve solo las acciones de lectura a un token que no puede escribir y desactiva las herramientas que requieren scopes que el token no posee. GITLAB_MCP_READ_ONLY=true mantiene en solo lectura también un token que podría escribir, como defensa en profundidad.

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

El modo solo lectura (GITLAB_MCP_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_MCP_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 verificación te toca a ti, porque el servidor nunca descarga un binario por ti: 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

Referencia de la fuente

Mantenido por José Manuel Requena PlensGitHub LinkedIn Mastodon Google Scholar Todos los proyectos