Configuración

Una variable obligatoria
Modo solo lectura
Vistas previas en modo seguro
Tier detectado de la licencia o el plan

El modo stdio lee variables de entorno (más ~/.gitlab-mcp-server.env y cualquier archivo que nombre GITLAB_MCP_ENV_FILE); el modo HTTP lee flags de CLI. Los nombres de las opciones se corresponden entre sí.
Un .env en el directorio de trabajo no se lee. Ese directorio viene del repositorio que abrió tu editor, así que su contenido lo eligió otra persona. Si existe uno, el arranque lo nombra en el log junto con las claves que pretendía definir.
En modo stdio solo GITLAB_TOKEN es obligatorio. GITLAB_URL usa https://gitlab.com por defecto, así que solo las instancias autogestionadas necesitan definirla. En modo HTTP el servidor necesita la instancia (--gitlab-url o GITLAB_URL) y ningún token, porque cada cliente envía el suyo.
Tres interruptores gobiernan el comportamiento: GITLAB_MCP_TOOL_SURFACE elige dinámico, meta o individual; GITLAB_MCP_READ_ONLY elimina toda operación de escritura; GITLAB_MCP_SAFE_MODE previsualiza las escrituras en lugar de ejecutarlas.

GitLab MCP Server casi no necesita nada para arrancar. En modo stdio, el predeterminado que usan las integraciones con IDE, solo estableces dos cosas: con qué instancia de GitLab hablar (GITLAB_URL) y un personal access token para hacerlo (GITLAB_TOKEN). En GitLab.com hasta la URL es opcional, porque GITLAB_URL usa https://gitlab.com por defecto, así que un único GITLAB_TOKEN basta; apunta GITLAB_URL a tu propio host para instancias autogestionadas. En modo HTTP el servidor no guarda credencial alguna: cada cliente envía su propio token en cada petición y, cuando el despliegue publica varias instancias de GitLab, la que elige. Todo lo demás en esta página es opcional y viene con un valor predeterminado seguro.

El modo stdio lee su configuración de variables de entorno, y recurre a ~/.gitlab-mcp-server.env y a cualquier archivo que nombre GITLAB_MCP_ENV_FILE; el modo HTTP lee flags de CLI. Esta página cubre las opciones que la mayoría de usuarios necesita; la referencia de variables de entorno recoge todas las variables y la referencia CLI todos los flags.

Nombres de las variables

Los ajustes que define este proyecto se leen como GITLAB_MCP_<NOMBRE> desde la 2.8.0.

Un servidor MCP por stdio se ejecuta en la shell desde la que arrancó su cliente, junto a todas las demás herramientas de esa persona. Nombres tan genéricos como LOG_LEVEL, AUTH_MODE o RATE_LIMIT_RPS pueden pertenecer ya a otra cosa, y la colisión es silenciosa: el servidor lee un valor que nadie le dio y se comporta como nadie configuró.

Las grafías anteriores a la 2.8.0 se eliminaron en la 3.1.0 y nada las lee: los nombres genéricos sin prefijo (TOOL_SURFACE, LOG_LEVEL y el resto), los interruptores que ya empezaban por GITLAB_ (GITLAB_TIER, GITLAB_READ_ONLY, GITLAB_SAFE_MODE, GITLAB_IGNORE_SCOPES, GITLAB_SKIP_TLS_VERIFY) y YOLO_MODE. Si queda alguna definida, en el entorno o en un fichero dotenv que el servidor carga, se nombra al arrancar junto con la variable a la que hay que renombrarla.

Iban a desaparecer en la 3.0.0 y se mantuvieron una versión más, porque la 2.7.5 lleva un autoactualizador y la 3.0.0 no: un despliegue 2.7.5 se actualiza solo a la 3.0.0 sin que nadie lea una nota de versión, así que quitarlas ahí habría roto esos despliegues en silencio. La 3.1.0 es la primera versión a la que nadie llega arrastrado. GITLAB_ENTERPRISE, retirada antes en favor del tier, se eliminó en la 3.0.0 y se ignora.

Tres de ellas impiden el arranque en lugar de avisar: GITLAB_READ_ONLY, GITLAB_SAFE_MODE y EXCLUDE_TOOLS. Retiran parte de lo que sirve un despliegue, así que una versión que ignorase una en silencio serviría escrituras, o las acciones que el operador quitó. El rechazo mira el nombre y nunca su valor. EXCLUDE_TOOLS es lo bastante genérico como para que lo use otra herramienta de la misma shell: renómbralo a GITLAB_MCP_EXCLUDE_TOOLS, o quítalo del entorno de este servidor si pertenece a otra.

Algunos nombres se mantienen sin prefijo a propósito:

Nombres	Por qué no se renombraron
`GITLAB_URL`, `GITLAB_TOKEN`	Son la convención de GitLab. Toda configuración existente las define, y son las dos que más probablemente se escriban de memoria en un cliente
`OTEL_*`	Pertenecen a la especificación de OpenTelemetry. Los exportadores leen esos nombres directamente y nunca verían una grafía prefijada
`AUTOPILOT`	Convención que fija otra herramienta de agentes, respetada como alias de `GITLAB_MCP_YOLO_MODE` y sin aviso. El ajuste en sí es nuestro y lleva el prefijo; su grafía antigua `YOLO_MODE` se eliminó en la 3.1.0
`MODELEVAL_*`	Variables de la evaluación con modelos, fijadas por objetivos `make` de este repositorio. Configuran un arnés de pruebas que el servidor no enlaza, así que nunca aparecen junto a las de otra herramienta en una shell

Las tablas siguientes siempre dan el nombre que hay que definir, así que léelo en lugar de deducirlo.

Variables requeridas

GitLab MCP Server requiere exactamente una variable para arrancar en modo stdio — el resto son opcionales y usan valores predeterminados seguros:

Variable	Descripción	Ejemplo
`GITLAB_TOKEN`	Personal access token: uno clásico con el scope `api` o `read_api`, o uno de grano fino cuya concesión decide lo que se le sirve. Qué token explica qué se sirve a cada tipo	`glpat-xxxxxxxxxxxxxxxxxxxx`

Qué token

Token	Qué le sirve el servidor
Clásico, scope `api`	Todas las acciones que permite el tier. Los cinco grupos de administración necesitan además `admin_mode` (Filtrado de herramientas por scopes)
Clásico, scope `read_api`	Solo las acciones de lectura: el servidor lee los scopes del token al arrancar (por credencial del pool en modo HTTP) y construye una superficie de solo lectura
De grano fino (sus scopes son `granular`)	Lo que alcanza su concesión, juzgado acción por acción frente a los permisos que declara GitLab 19.4.1, cuando el token concede Personal Access Token: Read y Metadata: Read y la instancia ejecuta la versión 19.4 registrada (en GitLab.com, cuya versión es la preliminar de la siguiente versión menor, la concesión decide el listado); en otro caso, todo salvo las acciones que ningún token de grano fino alcanza. Consulta Tokens de grano fino

Un token cuyos scopes no se pueden leer se sirve como si pudiera escribir, y es el propio 403 de GitLab el que responde a una llamada que no puede hacer. Un token que GitLab acepta pero que no lleva ni read_api ni api no alcanza ninguna herramienta, así que se rechaza (Scopes del token).

Opciones principales

Variable	Predeterminado	Descripción
`GITLAB_URL`	`https://gitlab.com`	URL base de la instancia GitLab, con esquema `http://` o `https://`. Establécela para instancias autogestionadas
`GITLAB_MCP_SKIP_TLS_VERIFY`	`false`	Omitir verificación de certificados TLS para certificados autofirmados
`GITLAB_MCP_TOOL_SURFACE`	`dynamic`	Selector canónico del catálogo: `dynamic`, `meta` o `individual`
`GITLAB_MCP_CAPABILITY_SURFACE`	`full`	Selector del catálogo de recursos y prompts: `full` conserva el catálogo completo; `minimal` mantiene el manifiesto `gitlab://tools`, y desactiva recursos opcionales, prompts, guías de flujo y suscripciones a recursos. Consulta Superficie de capacidades
`GITLAB_MCP_META_PARAM_SCHEMA`	`opaque`	Estrategia de esquema de entrada para meta-herramientas: `opaque` (por defecto), `compact` (8,7x el tamaño de `opaque`) o `full` (18,3x). Solo afecta a los esquemas de meta-herramientas en `tools/list`; consulta Esquema de parámetros de meta-herramientas
`GITLAB_MCP_TIER`	(autodetectado)	Selector de edición de GitLab: `free`/`ce`, `premium` o `ultimate`. Cuando se establece, se usa tal cual, sin comprobar la licencia. Cuando se omite, se detecta en dos pasos: `GET /license`, el plan de la instancia, que en una autogestionada solo puede leer un administrador y en GitLab.com nadie; después, los planes de los namespaces que administra el token (`GET /namespaces`), que son la suscripción real en GitLab.com y siempre `default` en una autogestionada. Ese listado se lee de 100 en 100, y se detiene en el primer `ultimate` y, en todo caso, tras 10 páginas, así que una cuenta que administra más de 1.000 namespaces y cuyo único namespace de pago queda más allá de ese límite resuelve un tier inferior al que tiene. Si ningún paso responde, el tier es `free`, y una instancia enterprise registra un aviso que nombra este ajuste. El tier decide qué acciones Premium y Ultimate se sirven, y retira los campos de los esquemas de entrada que quedan por encima de él; los esquemas de salida se podan con tolerancia, así que los datos que lleva una respuesta siguen llegando al cliente
`GITLAB_MCP_READ_ONLY`	`false`	Elimina toda acción de escritura (crear, actualizar, eliminar). El filtro es por acción, así que las lecturas siguen funcionando en todas las superficies, y una meta-herramienta o `gitlab_execute_action` que sirve ambas cosas sigue sirviendo sus lecturas
`GITLAB_MCP_SAFE_MODE`	`false`	Intercepta las acciones de escritura y responde con una tarjeta de vista previa en lugar de ejecutarlas: una tarjeta Markdown que nombra la acción, con los argumentos que habría enviado en un bloque JSON. Las lecturas siguen funcionando; `GITLAB_MCP_READ_ONLY` tiene precedencia
`GITLAB_MCP_EMBEDDED_RESOURCES`	`true`	Incrustar la URI canónica del recurso MCP `gitlab://` en los resultados get que la llevan (veintidós acciones get, de proyectos y grupos a snippets y páginas wiki); usa `false` para clientes que no toleren bloques de contenido duplicados
`GITLAB_MCP_EXCLUDE_TOOLS`	(vacío)	Nombres de herramienta, de grupo o IDs de acción separados por comas (ej., `gitlab_project_delete,gitlab_admin`); se excluyen de la superficie de herramientas y de los recursos, suscripciones, prompts y autocompletados de argumentos que devuelven los mismos objetos, así que la retirada se aplica en todas las vías de petición. Las mismas formas alcanzan a las utilidades independientes en todas las superficies (`gitlab_interactive`, `interactive.issue_create`, `discover_project.resolve`), y una entrada que no nombra nada se registra como aviso en lugar de rechazarse. El aviso se escribe cuando se construye por primera vez un catálogo: al arrancar en stdio, y en modo HTTP la primera vez que se construye el catálogo de cada forma de configuración. La forma incluye el nivel de licencia, detectado por credencial salvo que se fije, y el recorte por los scopes de la credencial, así que el aviso puede escribirse más de una vez, y una entrada que no nombra nada para el nivel de un cliente puede seguir retirando acciones para el de otro. También nombra `gitlab_find_action` y `gitlab_execute_action`, las dos herramientas de la superficie dinámica, aunque esa superficie las retira por su nombre
`GITLAB_MCP_IGNORE_SCOPES`	`false`	Omitir el filtro de scopes y la reducción a solo lectura y registrar todas las herramientas sin importar los scopes. Los scopes del token se siguen leyendo, así que uno que no lleva ni `read_api` ni `api` se sigue rechazando, y la concesión de un token de grano fino sigue decidiendo lo que se le muestra
`GITLAB_MCP_LOG_LEVEL`	`info`	Nivel de verbosidad del log: `debug`, `info`, `warn`, `error`. El flag `--log-level` fija la misma variable y gana sobre ella
`GITLAB_MCP_PPROF_ADDR`	(vacío)	Sirve los manejadores de perfilado de Go (`net/http/pprof`) en esta dirección de loopback (`127.0.0.1:6060`), en un listener propio que arranca antes que el transporte; un host que no sea loopback se rechaza al arrancar, porque un perfil de heap es una copia de la memoria del proceso. Vacío no sirve nada. El flag `--pprof-addr` fija la misma variable
`GITLAB_MCP_ALLOW_PRIVATE_INSTANCES`	`false`	`true` permite que un destino que el operador no eligió sea una dirección privada, de loopback o CGNAT: una instancia que un cliente nombró en `GITLAB-URL` con `--allow-any-gitlab-url`, o un salto de redirección que salió de la instancia configurada. Una dirección que nombró `GITLAB_URL` o `--gitlab-url` nunca se comprueba, y las direcciones de metadatos de la nube se siguen rechazando diga lo que diga. El flag `--allow-private-instances` fija la misma variable. Consulta Conexiones salientes

Modos de herramientas

Modo	Variable	Herramientas expuestas	Indicado para
Conjunto dinámico (predeterminado)	`GITLAB_MCP_TOOL_SURFACE=dynamic`	`gitlab_find_action`, `gitlab_execute_action`	La mayoría de usuarios: el menor contexto de arranque, con todas las acciones del catálogo alcanzables
Meta-herramientas	`GITLAB_MCP_TOOL_SURFACE=meta`	34 en Free/CE, 40 en Premium autogestionado, 51 en Ultimate autogestionado, 52 en GitLab.com Ultimate	Clientes que prefieren despachadores consolidados por dominio con un parámetro `action`
Herramientas individuales	`GITLAB_MCP_TOOL_SURFACE=individual`	868 en Free/CE, 1022 en Premium autogestionado, 1088 en Ultimate autogestionado, 1094 en GitLab.com Ultimate con Orbit	Clientes que necesitan elegir herramientas una a una

Mantén la superficie dinámica predeterminada para los despliegues habituales de bajo consumo de tokens, y fija GITLAB_MCP_TOOL_SURFACE=meta solo cuando un cliente o flujo de trabajo prefiera meta-herramientas por dominio. Conjunto de herramientas dinámico explica el flujo find/execute y Meta-herramientas la correspondencia entre dominios y acciones.

Esquema de parámetros de meta-herramientas

GITLAB_MCP_META_PARAM_SCHEMA (--meta-param-schema en modo HTTP) decide solo qué muestra el inputSchema de cada despachador de meta-herramienta en tools/list. Los handlers validan y ejecutan los mismos parámetros con los tres modos, y ni lo que devuelve gitlab_find_action ni lo que contiene el manifiesto gitlab://tools cambia con él.

Modo	Qué muestra el `inputSchema` de una meta-herramienta	Tamaño de los esquemas de entrada servidos
`opaque` (predeterminado)	El sobre compacto `{action, params}`: los nombres de las acciones, y `params` como objeto abierto	La referencia
`compact`	Un `oneOf` discriminado con una rama por acción, sus nombres de propiedad y tipos, sin descripciones ni `$defs`	8,7x el total de `opaque`
`full`	Un `oneOf` discriminado con el esquema completo de cada acción, descripciones incluidas	18,3x el total de `opaque`

Los tamaños son bytes serializados de los esquemas de entrada de las meta-herramientas, sumados, tal como los mide la auditoría de tokens del repositorio. No son una medida de tokens de arranque: ninguno cuenta los recursos ni los prompts. En la superficie dinámica el ajuste no cambia nada, porque las dos herramientas dinámicas conservan sus propios esquemas y gitlab_find_action devuelve en línea el esquema de una acción; en la superficie individual se ignora, porque cada herramienta ya lleva su propio esquema tipado. Mantén opaque y lee gitlab://tools/{id} para los parámetros exactos de una acción.

Superficie de capacidades

GITLAB_MCP_CAPABILITY_SURFACE (--capability-surface en modo HTTP) decide qué recursos y prompts MCP se registran:

full (el predeterminado) registra todos los recursos, las guías de flujo, los prompts y el manifiesto gitlab://tools, y anuncia las suscripciones a recursos.
minimal conserva solo el manifiesto gitlab://tools y su plantilla gitlab://tools/{id}. Su handshake no declara la capacidad prompts, así que prompts/list y prompts/get responden JSON-RPC -32601 (método no encontrado) en lugar de una página vacía, y resources/subscribe no se anuncia.

logging/setLevel responde -32601 en ambas, porque el servidor escribe sus logs en stderr y nunca declara la capacidad logging.

Minimal no elimina ningún esquema de acción: gitlab_find_action devuelve los esquemas exactos en línea antes de llamar a gitlab_execute_action, y gitlab://tools/{id} sirve la entrada del manifiesto de una acción en todas las superficies. Lo que ahorra es el contexto de arranque compartido, medido en 9498 tokens para los recursos y prompts de full frente a 170 para minimal (tokenizador cl100k_base; la página del conjunto de herramientas dinámico tiene los totales por superficie). Solo existen estos dos modos: uno intermedio, como solo esquemas o recursos sin prompts, añadiría otro eje de configuración sin mejorar los flujos de bajo consumo que ya existen.

Opciones de administración

Variable	Predeterminado	Descripción
`GITLAB_MCP_CLIENT_COMPAT`	`auto`	Compatibilidad de respuesta por cliente: las sesiones de Codex reciben las prioridades fraccionarias de las anotaciones redondeadas a 0/1; `off` la desactiva. Ambos transportes; el flag `--client-compat` fija la misma variable. Elegir una respuesta a partir de `clientInfo` es una desviación deliberada de la especificación MCP
`GITLAB_MCP_DESCRIPTION_SUBSTITUTIONS`	vacío	Reescribe descripciones y títulos listados para validadores estrictos de pasarelas MCP: pares `old=new` separados por comas y aplicados en orden (la barra invertida escapa `\,` `\=` `\\`); un valor mal formado impide el arranque. Ambos transportes; el flag `--description-substitutions` fija la misma variable
`GITLAB_MCP_UPLOAD_MAX_FILE_SIZE`	`2GB`	Límite de tamaño para las herramientas de subida y de ficheros, incluidas las lecturas raw (en streaming y detenidas al llegar al límite); admite sufijos `KB`/`MB`/`GB`, con techo de 1 TB. Ambos transportes; el flag `--upload-max-file-size` fija la misma variable
`GITLAB_MCP_YOLO_MODE`	`false`	Omitir confirmaciones de acciones destructivas en todas las superficies (no recomendado): sin pregunta en las superficies meta e individual, y sin necesidad de `confirm: true` en la dinámica por defecto; consulta Acciones destructivas. Un valor no vacío gana a `AUTOPILOT`; el flag `--yolo-mode` fija la misma variable
`AUTOPILOT`	`false`	Igual que `GITLAB_MCP_YOLO_MODE`, y solo se lee mientras esa no esté definida o esté vacía: omitir confirmaciones destructivas en todas las superficies. No tiene flag propio
`GITLAB_MCP_ALLOWED_IMPORT_DIRS`	(vacío)	Directorios adicionales, separados por el separador de listas de rutas del sistema operativo, permitidos para archivos locales de importación de proyectos/grupos
`GITLAB_MCP_ALLOWED_UPLOAD_DIRS`	(vacío)	Directorios adicionales, separados por el separador de listas de rutas del sistema operativo, de los que una herramienta puede leer un archivo local (cualquier entrada `file_path` o `directory_path`). El directorio de trabajo (salvo que sea la raíz del sistema de archivos o el directorio personal del usuario, que se descartan como raíces implícitas) y el temporal del sistema se permiten siempre, y la ruta se resuelve antes a través de enlaces simbólicos
`GITLAB_MCP_ALLOWED_DOWNLOAD_DIRS`	vacío	Directorios adicionales, con la misma sintaxis y las mismas raíces siempre permitidas, en los que una herramienta puede escribir un archivo descargado (`output_path`). El archivo aparece en `output_path` solo cuando está completo, así que una descarga que falla o se cancela lo deja como estaba
`GITLAB_MCP_ENV_FILE`	(vacío)	Un archivo dotenv a cargar además de `~/.gitlab-mcp-server.env`. Se lee solo del entorno del proceso, así que ningún archivo que cargue el servidor puede nombrar otro. Indica una ruta absoluta; una relativa sigue al cliente a cada espacio de trabajo que abre, y el servidor avisa cuando la ve
`GITLAB_MCP_STDIO_MAX_LINE_BYTES`	4 MiB	Mensaje stdio más largo que se acepta, en bytes. Una línea más larga se rechaza y se responde, no se acumula. Coincide con el valor por defecto del propio SDK para el cuerpo HTTP, de modo que ambos transportes rechazan los mismos mensajes; súbelo solo para un cliente que incruste cargas base64 grandes
`GITLAB_MCP_MAX_LISTEN_STREAMS`	`64`	Flujos `subscriptions/listen` simultáneos que una credencial puede mantener abiertos; `0` elimina ese techo. Otros 512 por proceso no son configurables, porque la cifra por credencial se multiplica por cuantos tokens tenga quien llama. Se aplica a ambos transportes
`GITLAB_MCP_ACTION_TIMEOUT`	`65m`	Cancela una acción que siga en marcha tras este tiempo; `0` lo desactiva (límite 24h). Por encima de la espera más larga que ofrece cualquier acción. También corta una subida o descarga de un archivo que siga en marcha al llegar al límite. Ambos transportes; el modo HTTP tiene además `--action-timeout`
`GITLAB_MCP_DRAIN_DELAY`	`0`	Modo HTTP: tras `SIGTERM`, mantiene el listener abierto y responde `/health` con `503 draining` durante este tiempo antes de cerrarlo, para que un balanceador que sondea `/health` retire la instancia antes del cierre (límite 5m); `0` cierra al instante. También `--drain-delay`
`GITLAB_MCP_AUTH_MODE`	`legacy`	Autenticación en modo HTTP: `legacy` (un token enviado en cada petición en `PRIVATE-TOKEN` o `Authorization: Bearer`) u `oauth` (verificación de tokens Bearer según RFC 9728). También `--auth-mode`
`GITLAB_MCP_OAUTH_CACHE_TTL`	`15m`	Modo HTTP, OAuth: cuánto tiempo se reutiliza la identidad de un token verificado, de 1m a 2h. También `--oauth-cache-ttl`
`GITLAB_MCP_OAUTH_CLIENT_UID`	(vacío)	Modo HTTP, OAuth: uids de aplicaciones OAuth de GitLab, separados por comas, cuyos tokens se admiten. Vacío admite cualquier credencial que acepte la instancia; ponerlo rechaza también los tokens de acceso personal, que no pertenecen a ninguna aplicación. También `--oauth-client-uid`
`GITLAB_MCP_RATE_LIMIT_RPS`	`0`	Límite por credencial en req/s sobre toda llamada que llega a GitLab: `tools/call`, `resources/read`, `resources/subscribe`, `subscriptions/listen`, `prompts/get` (`0` lo desactiva), más `completion/complete` en un bucket propio diez veces más holgado en tasa y burst, y `tools/list` en un bucket propio que se rellena diez veces más despacio y conserva el mismo burst, cobrado porque gasta el procesador que comparten todos los inquilinos y no porque llegue a GitLab, y antes en un bucket que comparte todo el proceso, 3000 herramientas por segundo y no configurable. Ambos transportes: el valor por defecto es `0` en stdio y `10` en modo HTTP, donde `--rate-limit-rps` lo sobrescribe. En stdio esta variable es el único interruptor, porque stdio ignora el flag y lo dice al arrancar (por qué stdio lo deja desactivado). Como máximo `1000`
`GITLAB_MCP_RATE_LIMIT_BURST`	`40`	Tamaño del bucket de tokens cuando `GITLAB_MCP_RATE_LIMIT_RPS` > 0, como máximo `10000`

Archivo dotenv de ejemplo

Escríbelo en ~/.gitlab-mcp-server.env, o en cualquier ruta que después nombres en GITLAB_MCP_ENV_FILE. Un .env en el directorio de trabajo no se carga.

# Requeridas
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

# Opcionales
GITLAB_MCP_SKIP_TLS_VERIFY=false
GITLAB_MCP_TOOL_SURFACE=dynamic
GITLAB_MCP_READ_ONLY=false
GITLAB_MCP_SAFE_MODE=false
GITLAB_MCP_EXCLUDE_TOOLS=
GITLAB_MCP_IGNORE_SCOPES=false
GITLAB_MCP_EMBEDDED_RESOURCES=true
GITLAB_MCP_UPLOAD_MAX_FILE_SIZE=2GB
GITLAB_MCP_LOG_LEVEL=info

Para GitLab autogestionado, añade GITLAB_URL=https://gitlab.example.com. No pongas GITLAB_MCP_TIER salvo que quieras fijarlo: si está definido se usa sin comprobar la licencia, así que free en una instancia con licencia oculta sus acciones Premium y Ultimate.

Configuración de clientes

Crea .vscode/mcp.json en tu workspace:

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/ruta/a/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Configuración segura del token usando variables de entrada de VS Code:

{
  "inputs": [
    {
      "id": "gitlab-token",
      "type": "promptString",
      "description": "GitLab Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/ruta/a/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "${input:gitlab-token}"
      }
    }
  }
}

Cargar las variables desde un archivo con envFile:

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/ruta/a/gitlab-mcp-server",
      "envFile": "${userHome}/.config/gitlab-mcp-server.env"
    }
  }
}

VS Code carga las variables de ese archivo en el entorno del servidor, así que el JSON no lleva ningún secreto. Nombra un archivo fuera del espacio de trabajo, porque uno dentro viaja con el repositorio. El servidor lee ~/.gitlab-mcp-server.env por su cuenta, así que envFile solo hace falta para un archivo guardado en otro sitio.

Edita claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gitlab": {
      "command": "/ruta/a/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Crea .cursor/mcp.json en tu proyecto:

{
  "mcpServers": {
    "gitlab": {
      "command": "/ruta/a/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Escribe el token donde el servidor lo lee y registra después el comando:

# Pide el token sin mostrarlo, así que queda fuera del historial de la shell
printf 'GitLab token: ' && read -rs t && printf 'GITLAB_TOKEN=%s\n' "$t" > ~/.gitlab-mcp-server.env && unset t && echo
chmod 600 ~/.gitlab-mcp-server.env

claude mcp add gitlab \
  --transport stdio \
  -- /ruta/a/gitlab-mcp-server

Añade GITLAB_URL=https://gitlab.example.com a ese mismo archivo solo para instancias autogestionadas, o escribe el archivo entero con un editor. Ninguno de los dos comandos nombra el token, así que nada lo pone en argv, en el historial de la shell ni en el propio archivo de configuración de Claude Code.

Añade a ~/.continue/config.yaml; un espacio de trabajo puede en cambio guardar sus servidores como archivos en su carpeta .continue/mcpServers/, como describe la documentación MCP de Continue:

mcpServers:
  - name: gitlab
    command: /ruta/a/gitlab-mcp-server
    env:
      GITLAB_TOKEN: glpat-xxxxxxxxxxxxxxxxxxxx

Recarga la ventana de Continue tras editar la configuración. La entrada HTTP está en Configuración de clientes; Continue no documenta ningún flujo OAuth, así que por HTTP envía un token.

Edita ~/.codeium/windsurf/mcp_config.json (Cascade → Plugins → Configure):

{
  "mcpServers": {
    "gitlab": {
      "command": "/ruta/a/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Reinicia Windsurf o pulsa Refresh en el panel de Plugins para que se apliquen los cambios.

Los IDEs de JetBrains (IntelliJ IDEA, GoLand, PyCharm, etc.) con el plugin AI Assistant añaden servidores MCP en Settings > Tools > AI Assistant > Model Context Protocol (MCP). Selecciona Add, después el transporte STDIO, y pega:

{
  "mcpServers": {
    "gitlab": {
      "command": "/ruta/a/gitlab-mcp-server",
      "args": []
    }
  }
}

JetBrains documenta la entrada como un command y sus args, sin bloque de entorno, así que pon el token en ~/.gitlab-mcp-server.env, como en la pestaña de Claude Code, y añade ahí GITLAB_URL=https://gitlab.example.com para GitLab autogestionado. El servidor lee ese archivo por su cuenta.

Los ejemplos de arriba que escriben el token en el JSON del cliente son los más cortos de leer, no los más seguros de conservar: un .vscode/mcp.json o .cursor/mcp.json de un proyecto se sube al repositorio con facilidad. Configuración de clientes tiene la entrada de cualquier otro cliente.

Mantener el token fuera del archivo del cliente

El archivo de entorno del directorio personal. El servidor lee ~/.gitlab-mcp-server.env por sí mismo, así que una entrada puede omitir GITLAB_TOKEN por completo, como hacen las pestañas de Claude Code y JetBrains. Una variable que fija la entrada, aunque sea con un valor vacío, gana sobre el archivo. Recomendado: Archivo de entorno muestra cómo escribirlo sin que el token llegue al historial de la shell.
La gestión de secretos del propio cliente. VS Code pide el token con una variable de entrada, o carga un archivo con envFile (la pestaña de VS Code de arriba).
Una variable que el cliente sustituye. Cursor expande ${env:GITLAB_TOKEN} y OpenCode {env:GITLAB_TOKEN} a partir del entorno en el que arrancaron (Cursor, OpenCode), así que el token se exporta una vez y el archivo solo nombra la variable.

Para exportar la variable en Linux o macOS, añádela al perfil de tu shell; un cliente arrancado desde esa shell la hereda:

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

En Windows, fíjala para tu usuario en PowerShell 7.1 o posterior, que pide el valor sin mostrarlo, y reinicia después el cliente:

[Environment]::SetEnvironmentVariable('GITLAB_TOKEN', (Read-Host 'GitLab token' -MaskInput), 'User')

No todos los clientes transmiten su entorno. GitHub documenta que Copilot CLI entrega a un servidor local PATH y las variables del bloque env de ese servidor, y nada más, así que un GITLAB_TOKEN exportado no llega allí al servidor: guárdalo en el bloque env de ~/.copilot/mcp-config.json, que vive en tu directorio personal y no en un proyecto.

Flags del modo HTTP

Un servidor stdio no lee ninguno de los flags de la primera tabla de abajo salvo el propio --http, porque su configuración sale del entorno. Si recibe alguno, lo ignora y lo dice una vez al arrancar, nombrando cada flag junto a la variable que hay que fijar en su lugar, en WARN (o en INFO cuando fue --transport=auto quien eligió stdio y stdio no tiene ese ajuste en absoluto, como el listener). Cuando ignorar el flag costaría más que un ajuste, un servidor stdio se niega a arrancar y nombra la variable que hay que fijar en su lugar, aunque esa variable ya pida lo mismo: --read-only, --safe-mode o --exclude-tools pidiendo retener algo que entonces serviría, y un --gitlab-url que no nombra ninguna instancia a la que se conecte, porque enviaría GITLAB_TOKEN a la que nombra GITLAB_URL, https://gitlab.com si no está definida.

En modo HTTP (--http), los ajustes se resuelven en tres capas, de mayor a menor prioridad: un flag de CLI pasado explícitamente, después la variable de entorno correspondiente y por último el valor por defecto. Por eso se respeta una variable exportada sin su flag, y una cuyo valor no se puede interpretar impide el arranque en lugar de descartarse en silencio. Unos pocos flags, entre ellos los del listener, no tienen equivalente en entorno:

Flag	Predeterminado	Descripción
`--http`	`false`	Habilitar modo de transporte HTTP
`--http-addr`	`:8080`	Dirección de escucha. `host:puerto` abre un socket TCP; un valor con separador de rutas (p. ej. `/run/gitlab-mcp.sock`) abre un socket unix. Sin equivalente en entorno
`--http-socket-mode`	`0660`	Modo de permisos en octal del socket unix indicado en `--http-addr`: pueden conectar el propietario y el grupo, nadie más. Sin equivalente en entorno
`--tls-cert` / `--tls-key`	(vacío)	Certificado y clave PEM. Sirve HTTPS en el propio listener (mínimo TLS 1.2; se negocia 1.3). Ambos o ninguno. Un par que no carga impide el arranque; después, un par que cambia se vuelve a leer en el siguiente handshake, así que rotar el certificado no exige reiniciar. Sin equivalente en entorno
`--gitlab-url`	(obligatorio)	URL de la instancia de GitLab. Obligatoria salvo que se pase `--allow-any-gitlab-url`; `GITLAB_URL` la aporta cuando no se da el flag. Repítela (o sepárala por comas) para publicar varias instancias, entre las que la cabecera `GITLAB-URL` pasa a ser obligatoria
`--allow-any-gitlab-url`	`false`	Arranca sin publicar ninguna instancia y deja que `GITLAB-URL` nombre cualquier host. Solo para despliegues locales de un único usuario: se rechaza salvo que `--http-addr` escuche en una dirección de loopback o en un socket unix, y aun ahí avisa al arrancar. Sin equivalente en entorno
`--skip-tls-verify`	`false`	Omitir verificación TLS
`--tool-surface`	(vacío)	Selector canónico del catálogo: `dynamic`, `meta` o `individual`; vacío sirve `dynamic`
`--meta-param-schema`	`opaque`	Modo de schema para `params` de meta-herramientas: `opaque`, `compact` o `full`; solo afecta schemas de meta-herramientas
`--capability-surface`	`full`	Selector del catálogo de recursos y prompts: `full` o `minimal`; minimal mantiene el manifiesto `gitlab://tools`, y omite recursos opcionales, guías y prompts
`--tier`	(autodetectado)	Forzar la edición de GitLab: `free`/`ce`, `premium` o `ultimate`; omítelo para autodetectar CE/EE por entrada token+URL. Sustituye a `GITLAB_ENTERPRISE`, que se eliminó en 3.0.0 y se ignora; no existe ningún flag `--enterprise`
`--read-only`	`false`	Modo solo lectura: elimina toda acción de escritura, acción por acción, y las lecturas siguen funcionando en todas las superficies
`--safe-mode`	`false`	Intercepta las acciones de escritura y responde con una tarjeta de vista previa en lugar de ejecutarlas: una tarjeta Markdown que nombra la acción, con los argumentos en un bloque JSON
`--embedded-resources`	`true`	Incrustar la URI canónica del recurso MCP en los resultados get que la llevan (veintidós acciones get)
`--exclude-tools`	(vacío)	Nombres de herramienta, de grupo o IDs canónicos de acción separados por comas; se excluyen de la superficie de herramientas y de los recursos, suscripciones, prompts y autocompletados de argumentos que devuelven los mismos objetos. Las mismas formas alcanzan a las utilidades independientes en todas las superficies, y una entrada que no nombra nada se registra como aviso, según describe `GITLAB_MCP_EXCLUDE_TOOLS`
`--ignore-scopes`	`false`	Omitir el filtro de scopes y la reducción a solo lectura. Un token que no lleva ni `read_api` ni `api` se sigue rechazando, y la concesión de un token de grano fino sigue decidiendo lo que se le muestra
`--max-http-clients`	`100`	Número máximo de entradas (token, URL de GitLab) en el pool, de 1 a 10000; acota entradas del pool, no las sesiones ni las peticiones que retienen, que el proceso acota según su límite de descriptores (192 llamadas retenidas y 96 sesiones con estado a la vez bajo un límite duro de 1024), sin opción de configurarlo
`--session-timeout`	`30m`	Tiempo de inactividad de la sesión MCP; solo con `--stateless=false`; con el transporte stateless por defecto, la sesión de cada POST termina con su respuesta. Una sesión que el cliente nunca borra ocupa una de las plazas de sesión del proceso hasta que caduca, y con `0` hasta que el pool desaloja su credencial
`--http-idle-timeout`	`0` (desactivado)	Timeout de conexión inactiva del servidor HTTP. `0` (por defecto) desactiva el cierre por inactividad, de modo que `--session-timeout` es la vida efectiva; usa una duración positiva para reciclar conexiones antes
`--stateless`	`true`	Streamable HTTP sin sesión (protocolo 2026-07-28): sin seguimiento de `Mcp-Session-Id`, cada POST es autocontenido, GET y DELETE responden `405`. `--stateless=false` recupera las sesiones con estado heredadas. Sin equivalente en entorno
`--json-response`	`false`	Devolver cuerpos de respuesta `application/json` en lugar de `text/event-stream` (SSE). Sin equivalente en entorno
`--max-request-body-bytes`	`0`	Tamaño máximo del cuerpo de una petición streamable HTTP, en bytes; `0` usa el valor por defecto del SDK (4 MiB). Un cuerpo mayor se rechaza con `413`. Sin equivalente en entorno
`--auth-mode`	`legacy`	Modo de autenticación: `legacy` u `oauth`
`--oauth-cache-ttl`	`15m`	TTL de caché de identidad OAuth (1m–2h)
`--oauth-client-uid`	(vacío)	uids de aplicaciones OAuth de GitLab, separados por comas, cuyos tokens se admiten. Vacío admite cualquier credencial que acepte la instancia; ponerlo rechaza también los tokens de acceso personal, que no pertenecen a ninguna aplicación
`--public-url`	(vacío)	Origen accesible desde fuera (`https://host[:puerto][/ruta]`, `http` solo para un host de loopback, sin barra final). Obligatorio con `--auth-mode=oauth`; su origen también es de confianza para peticiones cross-origin de navegador. Entorno: `GITLAB_MCP_PUBLIC_URL`
`--resource-documentation`	(vacío)	URL https publicada como `resource_documentation` de RFC 9728; apúntala a una página que describa tu propia aplicación OAuth (su client ID y sus URI de redirección registradas). Vacío publica la página Aplicación OAuth de este proyecto
`--resource-policy-uri`	(vacío)	URL https publicada como `resource_policy_uri` de RFC 9728; tu propia página sobre qué hace este despliegue con los datos a los que accede. Vacío omite el campo
`--resource-tos-uri`	(vacío)	URL https publicada como `resource_tos_uri` de RFC 9728; tus propias condiciones de servicio. Vacío omite el campo
`--trusted-origins`	(vacío)	Orígenes separados por comas permitidos para peticiones cross-origin de navegador; `*` acepta cualquier origen. Vacío no añade ninguno, aunque el origen de `--public-url` es de confianza igualmente. Entorno: `GITLAB_MCP_TRUSTED_ORIGINS`
`--action-timeout`	`65m`	Cancela una acción que siga en marcha tras este tiempo; `0` lo desactiva (límite: 24h). Toma su valor de `GITLAB_MCP_ACTION_TIMEOUT` si no se pasa
`--drain-delay`	`0`	Tras `SIGTERM`, mantiene el listener abierto y responde `/health` con `503 draining` durante este tiempo antes de cerrarlo (límite: 5m); `0` cierra al instante. Toma su valor de `GITLAB_MCP_DRAIN_DELAY` si no se pasa
`--pool-idle-timeout`	`1h`	Recupera una entrada de credencial del pool (token + URL de GitLab) tras este tiempo sin usarse; `0` mantiene las entradas hasta que el límite de tamaño del pool las expulse (límite: 24h). Una entrada con una suscripción viva nunca está inactiva según esta medida: su watcher sondea GitLab directamente y su listen es una única petición que el cliente nunca repite, así que nada la refrescaría
`--revalidate-interval`	`15m`	Intervalo de revalidación del token (límite: 24h). `0` detiene la comprobación periódica, pero una entrada cuya credencial tenga más de 1h se reconstruye igualmente, lo que vuelve a ejecutar la sonda
`--rate-limit-rps`	`10`	Límite de tasa por credencial, en req/s, sobre toda llamada que llega a GitLab: `tools/call`, `resources/read`, `resources/subscribe`, `subscriptions/listen`, `prompts/get` (`0` lo desactiva), más `completion/complete` en un bucket propio diez veces más holgado en tasa y burst, y `tools/list` en un bucket propio que se rellena diez veces más despacio y conserva el mismo burst, cobrado por gastar el procesador compartido y no por llegar a GitLab, y antes en un bucket que comparte todo el proceso, 3000 herramientas por segundo y no configurable; activo por defecto porque un despliegue HTTP es compartido. Como máximo `1000`
`--rate-limit-burst`	`40`	Tamaño del token bucket cuando `--rate-limit-rps > 0`, como máximo `10000`
`--trusted-proxies`	(vacío)	Direcciones o rangos CIDR de los proxies inversos cuya `--trusted-proxy-header` se cree (ej. `127.0.0.1,10.0.0.0/8`); desde cualquier otro origen la cabecera se ignora. Obligatoria junto a `--trusted-proxy-header`
`--trusted-proxy-header`	(vacío)	Cabecera HTTP con la IP real del cliente (ej. `CF-Connecting-IP`, `X-Forwarded-For`), para que los presupuestos de fallos de autenticación carguen a quien llama y no al proxy; solo se cree desde `--trusted-proxies`

Los cuatro flags de los presupuestos de autenticación (--auth-failure-limit, --auth-failure-window, --auth-distinct-token-limit, --auth-distinct-token-window) se explican en Presupuestos de autenticación; cada límite admite como máximo 100000 y cada ventana como máximo 24h.

Flags generales (modos stdio y HTTP):

Flag	Predeterminado	Descripción
`--transport`	(vacío)	`stdio`, `http` o `auto`. Vacío se remite a `--http`; `auto` sirve HTTP solo cuando la entrada estándar es el dispositivo nulo (un contenedor arrancado sin `-i`) y stdio para la tubería que conecta un cliente MCP
`--env-file`	(vacío)	Archivo dotenv a cargar además de `~/.gitlab-mcp-server.env`; el mismo ajuste que `GITLAB_MCP_ENV_FILE`, y gana sobre ella
`--log-level`	(vacío)	`debug`, `info` (el valor efectivo por defecto), `warn` o `error`. Fija `GITLAB_MCP_LOG_LEVEL`
`--client-compat`	(vacío)	`auto` (el valor efectivo por defecto) u `off`. Fija `GITLAB_MCP_CLIENT_COMPAT`
`--upload-max-file-size`	(vacío)	Límite de tamaño para las herramientas de subida y de lectura de ficheros, con sufijos `KB`/`MB`/`GB` (`2GB` si no se indica). Fija `GITLAB_MCP_UPLOAD_MAX_FILE_SIZE`
`--yolo-mode`	(vacío)	`true` omite la confirmación de las acciones destructivas en todas las superficies, la dinámica por defecto incluida. Fija `GITLAB_MCP_YOLO_MODE`
`--description-substitutions`	(vacío)	Pares `old=new` separados por comas aplicados a toda descripción y título listados. Fija `GITLAB_MCP_DESCRIPTION_SUBSTITUTIONS`; un valor mal formado impide el arranque
`--allow-private-instances`	(vacío)	`true` permite que un destino que el operador no eligió (una cabecera `GITLAB-URL` con `--allow-any-gitlab-url`, o un salto de redirección que salió de la instancia) sea una dirección privada, de loopback o CGNAT; las direcciones de metadatos de la nube se siguen rechazando. Fija `GITLAB_MCP_ALLOW_PRIVATE_INSTANCES`
`--pprof-addr`	(vacío)	Sirve los manejadores de perfilado de Go en esta dirección de loopback (`127.0.0.1:6060`), en un listener propio; cualquier otro host se rechaza al arrancar. Fija `GITLAB_MCP_PPROF_ADDR`
`--tool-search`	(vacío)	Busca en el catálogo de acciones por nombre, alias, etiqueta o descripción y sale; imprime cada ID canónico de acción junto al nombre que le da la superficie configurada. Lee `--tool-surface` y `--tier`, y en su defecto `GITLAB_MCP_TOOL_SURFACE` y `GITLAB_MCP_TIER`
`--version`	`false`	Imprimir la versión y el commit, y salir
`--shutdown`	`false`	Terminar todas las instancias en ejecución y salir
`--probe`	`false`	Preguntar por `/health` a la instancia en ejecución y salir con 0 si responde; el `HEALTHCHECK` de la imagen. Lee el listener de los propios flags de la instancia, o sondea la URL, `unix:<ruta>` o `host:puerto` dados tras el flag

Los siete flags que fijan una variable (de --log-level a --pprof-addr) existen para que una sola línea de comandos configure el servidor entero; un flag pasado explícitamente gana a una variable exportada. GITLAB_TOKEN no tiene flag a propósito, porque un token en la línea de comandos es visible para todos los usuarios de la máquina a través de ps y acaba en el historial de la shell. Los cuatro flags de telemetría (--telemetry, --telemetry-identity, --telemetry-identity-rotation, --telemetry-tool-name) también los leen ambos transportes, y Telemetría los explica. -h o --help imprime la ayuda del propio servidor, y la referencia CLI recoge todos los flags con su tipo.

Ejemplo:

# Instancia única de GitLab.com (URL fija para todos los clientes; reemplázala para GitLab autogestionado)
./gitlab-mcp-server \
  --http \
  --http-addr=0.0.0.0:8080 \
  --gitlab-url=https://gitlab.com \
  --max-http-clients=200 \
  --session-timeout=1h

# Varias instancias (la cabecera GITLAB-URL es obligatoria y debe nombrar una de ellas)
./gitlab-mcp-server \
  --http \
  --http-addr=0.0.0.0:8080 \
  --gitlab-url=https://gitlab.com,https://gitlab.example.com

Orden de carga de la configuración

El servidor carga la configuración en el siguiente orden (las fuentes posteriores anulan las anteriores):

~/.gitlab-mcp-server.env: valores predeterminados a nivel de usuario (directorio personal)
El archivo que nombre GITLAB_MCP_ENV_FILE: un dotenv adicional, si el entorno nombra alguno
Variables de entorno del sistema: lo que pasó el cliente MCP, o lo que exportó el shell
Flags de CLI (prioridad más alta): en modo HTTP, toda la tabla HTTP; en stdio, solo los flags generales y los de telemetría, entre ellos los que fijan una variable, porque un servidor stdio nombra cada flag HTTP que recibe y lo ignora, o se niega a arrancar (consulta Flags del modo HTTP)

Un archivo dotenv nunca sobrescribe una variable que ya está definida, y eso es lo que hace que una fuente anterior pierda frente a una posterior en esta lista.

Un .env en el directorio de trabajo no se carga

Un servidor stdio hereda el directorio de trabajo de su cliente, y todo editor lo fija en el espacio de trabajo que abrió. El archivo llega, por tanto, con un repositorio clonado o un archivo comprimido desempaquetado, escrito por alguien que no eres tú. Cargarlo primero permitía que dos líneas de un repositorio apuntaran tu token a otro host, desactivaran la verificación de certificados para que nada protestara y reescribieran las descripciones de herramientas que lee el modelo, todo ello antes de ejecutar ninguna herramienta.

Si existe uno, se sigue buscando y el arranque lo nombra a nivel WARN, con su ruta absoluta y las claves que pretendía definir, de modo que un archivo que dejó de surtir efecto aparece en el log en lugar de costarte una tarde de depuración. Para seguir usándolo, nómbralo por ruta absoluta en GITLAB_MCP_ENV_FILE, que se lee solo del entorno, así que ningún archivo que cargue el servidor puede nombrar otro. Un valor relativo ahí se resuelve contra el directorio de trabajo del cliente y lo sigue a cada espacio de trabajo que abre, que es justo el comportamiento que esto sustituye, así que el servidor avisa de ello.

Certificados autofirmados

Para instancias de GitLab con certificados TLS autofirmados:

GITLAB_MCP_SKIP_TLS_VERIFY=true

Modo solo lectura

Habilita GITLAB_MCP_READ_ONLY=true para restringir el servidor a operaciones de solo lectura. Toda acción que crea, actualiza o elimina se retira, acción por acción, y las lecturas siguen funcionando en todas las superficies. Esto es útil para:

Entornos de auditoría y cumplimiento
Servidores compartidos donde los usuarios solo deben consultar datos
Tokens con scope read_api

Qué expone: todas las operaciones de lectura, en todas las superficies: list, get y search siguen funcionando exactamente igual.
Requiere: GITLAB_MCP_READ_ONLY=true en modo stdio, --read-only en modo HTTP.
Qué no hace: todo lo que escribe: las acciones de crear, actualizar y borrar se eliminan del catálogo por acción, así que en las superficies dinámica y meta dejan de ser alcanzables en lugar de simplemente fallar. Si el modo seguro también está activo, solo lectura gana — las mutaciones desaparecen en vez de previsualizarse.

Modo seguro

Habilita GITLAB_MCP_SAFE_MODE=true para interceptar las acciones de escritura y responder con una vista previa de lo que se ejecutaría, sin realizar la operación. La vista previa es una tarjeta Markdown: un encabezado ⛔ Safe mode blocked que nombra la acción, las filas Status y Mode con blocked y safe, una fila Tool, los argumentos que habría enviado en un bloque JSON y la indicación Set GITLAB_MCP_SAFE_MODE=false to execute this operation. En las superficies dinámica y meta la tarjeta nombra la acción canónica y el resultado estructurado lleva los mismos campos; en la superficie individual nombra la herramienta y llega como resultado de error, porque la herramienta no produjo nada de la salida que describe su esquema. Las lecturas funcionan con normalidad. Esto es útil para:

Revisar operaciones antes de ejecutarlas (dry-run)
Entornos de formación donde se quiere ver el comportamiento de las herramientas
Depurar parámetros de herramientas sin efectos secundarios

Qué expone: la forma de cada operación: las acciones de escritura siguen siendo invocables y responden con una tarjeta de vista previa que nombra la acción canónica (por ejemplo issue.create), con los parámetros que enviaría en un bloque JSON; las lecturas se ejecutan con normalidad.
Requiere: GITLAB_MCP_SAFE_MODE=true en modo stdio, --safe-mode en modo HTTP.
Qué no hace: escrituras reales: nada mutador llega a GitLab. La vista previa tampoco es una validación — los errores del lado de GitLab (permisos, conflictos) solo aparecen en una ejecución real.

Tanto el modo seguro como el de solo lectura actúan por acción, no por herramienta. En las superficies dinámica y meta una sola herramienta sirve muchas acciones —gitlab_execute_action enruta todo y gitlab_issue cubre por igual list y create—, así que la política se aplica sobre el catálogo de acciones subyacente. Las lecturas siguen funcionando en todas las superficies, y las vistas previas del modo seguro nombran la acción canónica (por ejemplo issue.create) en lugar de la herramienta despachadora.

Comportamientos automáticos

Siempre están activos y no requieren configuración:

Función	Qué hace
Anotaciones de contenido	Cada bloque Markdown de un resultado de herramienta se anota para la audiencia `assistant`, con una prioridad de `0.7` salvo que la acción declare un tipo lista, detalle o mutación (consulta Anotaciones de contenido). El Markdown sirve al modelo para razonar y el JSON de `structuredContent` a los programas, así que un cliente que muestra ambos no enseña dos veces la misma respuesta. Un bloque de imagen va en cambio a la audiencia `user`
Enlaces pulsables	Los resultados de lista enlazan cada objeto de GitLab que nombran (merge requests, issues, pipelines y el resto) como `[text](url)`, y abren sus indicaciones con una que pide al modelo conservar los enlaces
Próximos pasos	Un resultado que sugiere una continuación termina con un bloque `💡 Next steps`, y la salida estructurada lleva las mismas indicaciones como array `next_steps` allí donde el tipo de salida de la acción lo declara
Fechas formateadas	El Markdown muestra una marca de tiempo en UTC como `15 Jan 2025 10:30 UTC`, y una fecha sola como `15 Jan 2025`; la salida estructurada conserva RFC 3339 en UTC, para que un cliente pueda interpretarla

La referencia del formato de salida describe un resultado al completo.

Preguntas frecuentes

¿Cuál es la configuración mínima?

En modo stdio, un único GITLAB_TOKEN con el scope api basta para arrancar — cualquier otra variable es opcional y usa un valor predeterminado seguro. GITLAB_URL usa https://gitlab.com por defecto, así que solo la estableces al conectar a una instancia autogestionada. Para una configuración de solo lectura, usa un token read_api: el servidor le sirve por sí solo una superficie de solo lectura, y GITLAB_MCP_READ_ONLY=true hace lo mismo con un token api. En modo HTTP no se configura ningún token en el servidor; cada cliente envía el suyo en cada petición.

stdio vs HTTP — ¿qué modo uso?

Usa el modo stdio (el predeterminado) para configuraciones locales de un solo usuario como integraciones con IDE (VS Code, Cursor, Claude Desktop); se configura mediante variables de entorno, más ~/.gitlab-mcp-server.env o el archivo que nombre GITLAB_MCP_ENV_FILE para lo que el entorno no traiga. Usa el modo HTTP (--http) para despliegues compartidos o remotos como Docker o Kubernetes, donde la configuración usa flags de CLI y cada cliente se autentica con su propio token de GitLab en cada petición.

¿Cómo apunto a una instancia de GitLab autogestionada?

Establece GITLAB_URL con la URL base de tu instancia, por ejemplo GITLAB_URL=https://gitlab.example.com (en modo HTTP, usa el flag --gitlab-url). Si la instancia usa un certificado autofirmado o de CA interna, establece también GITLAB_MCP_SKIP_TLS_VERIFY=true (o --skip-tls-verify en modo HTTP), pero solo en una red de confianza — desactiva la verificación de certificados para todas las conexiones a GitLab.

¿Cómo elijo una superficie de herramientas (dynamic, meta o individual)?

Establece la variable GITLAB_MCP_TOOL_SURFACE (o el flag --tool-surface en modo HTTP). dynamic es la predeterminada y la de menor consumo de tokens: expone gitlab_find_action y gitlab_execute_action mientras mantiene cada acción de GitLab accesible a través del catálogo canónico de acciones. Elige meta cuando un cliente prefiere despachadores consolidados por dominio con un parámetro action, e individual para registrar una herramienta MCP por cada operación de GitLab.

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