Ir al contenido
GitLab MCP Server

Configuración

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

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 (y, opcionalmente, su propia URL de GitLab) en cada petición. 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; consulta la referencia de variables y la referencia CLI del repositorio para las tablas exhaustivas.

Nombres de las variables

Sección titulada «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ó.

La grafía sin prefijo sigue funcionando y se elimina en la v3. Cuando ambas están definidas gana la prefijada, y un aviso al arrancar nombra la que se ignora.

Algunos nombres se mantienen sin prefijo a propósito:

NombresPor qué no se renombraron
GITLAB_URL, GITLAB_TOKENSon 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
GITLAB_MCP_SKIP_TLS_VERIFY, GITLAB_MCP_TIER, GITLAB_MCP_READ_ONLY, GITLAB_MCP_SAFE_MODE, GITLAB_MCP_IGNORE_SCOPESYa llevan el espacio de nombres GITLAB_. Un segundo prefijo rompería toda configuración existente sin proteger de nada
OTEL_*Pertenecen a la especificación de OpenTelemetry. Los exportadores leen esos nombres directamente y nunca verían una grafía prefijada
GITLAB_MCP_YOLO_MODE, AUTOPILOTConvenciones que fija otra herramienta de agentes. Respetar el nombre que ya usa esa herramienta es justamente el motivo de leerlas
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

Sección titulada «Variables requeridas»

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

VariableDescripciónEjemplo
GITLAB_TOKENPersonal Access Token con scope apiglpat-xxxxxxxxxxxxxxxxxxxx

Opciones principales

Sección titulada «Opciones principales»
VariablePredeterminadoDescripción
GITLAB_URLhttps://gitlab.comURL base de la instancia GitLab. Establécela para instancias autogestionadas
GITLAB_MCP_SKIP_TLS_VERIFYfalseOmitir verificación de certificados TLS para certificados autofirmados
GITLAB_MCP_TOOL_SURFACEdynamicSelector canónico del catálogo: dynamic, meta o individual
GITLAB_MCP_CAPABILITY_SURFACEfullSelector 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
GITLAB_MCP_META_PARAM_SCHEMAopaqueEstrategia 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; mide las proporciones actuales con go run ./cmd/audit_tokens --compare-schemas
GITLAB_MCP_TIER(autodetectado)Selector de edición de GitLab: free/ce, premium o ultimate. Cuando se establece, se usa tal cual; cuando se omite, se detecta desde GET /license (por defecto free). El tier restringe las herramientas Enterprise/Premium y poda entradas de esquema por campo mediante pruneSchemaFieldsByTier (ver internal/tools/action_catalog.go)
GITLAB_MCP_READ_ONLYfalseDesactivar todas las herramientas de escritura (crear, actualizar, eliminar)
GITLAB_MCP_SAFE_MODEfalseDevolver vista previa JSON estructurada en lugar de ejecutar herramientas de escritura (modo dry-run)
GITLAB_MCP_EMBEDDED_RESOURCEStrueIncrustar 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—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 compleciones de argumentos que devuelven los mismos objetos, así que la retirada se sostiene en todas las vías de petición
GITLAB_MCP_IGNORE_SCOPESfalseOmitir detección automática de scopes del PAT — registrar todas las herramientas sin importar los scopes
GITLAB_MCP_LOG_LEVELinfoNivel 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

Opciones de administración

Sección titulada «Opciones de administración»
VariablePredeterminadoDescripción
GITLAB_MCP_CLIENT_COMPATautoCompatibilidad 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
GITLAB_MCP_DESCRIPTION_SUBSTITUTIONSvacíoReescribe 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_SIZE2GBLí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_MODEfalseOmitir confirmaciones de acciones destructivas (no recomendado). Un valor no vacío gana a AUTOPILOT; el flag --yolo-mode fija la misma variable
AUTOPILOTfalseIgual que GITLAB_MCP_YOLO_MODE: omitir confirmaciones destructivas. No tiene flag propio
GITLAB_MCP_ALLOWED_IMPORT_DIRS—Directorios adicionales, separados por la lista de rutas del sistema operativo, permitidos para archivos locales de importación de proyectos/grupos
GITLAB_MCP_ALLOWED_UPLOAD_DIRS—Directorios adicionales, separados por la lista 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—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)
GITLAB_MCP_ENV_FILE—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_BYTES4 MiBMensaje 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_STREAMS64Flujos 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_TIMEOUT65mCancela 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. Ambos transportes; el modo HTTP tiene además --action-timeout
GITLAB_MCP_DRAIN_DELAY0Modo 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_RATE_LIMIT_RPS0Lí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 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. Ambos transportes: el valor por defecto es 0 en stdio y 10 en modo HTTP, donde --rate-limit-rps lo sobrescribe
GITLAB_MCP_RATE_LIMIT_BURST40Tamaño del bucket de tokens cuando GITLAB_MCP_RATE_LIMIT_RPS > 0

Archivo dotenv de ejemplo

Sección titulada «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.

~/.gitlab-mcp-server.env
# Requeridas
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx


# Opcionales
GITLAB_MCP_SKIP_TLS_VERIFY=false
GITLAB_MCP_TOOL_SURFACE=dynamic
GITLAB_MCP_TIER=free
GITLAB_MCP_READ_ONLY=false
GITLAB_MCP_SAFE_MODE=false
GITLAB_MCP_EXCLUDE_TOOLS=
GITLAB_MCP_IGNORE_SCOPES=false
GITLAB_MCP_LOG_LEVEL=info

Para GitLab autogestionado, añade GITLAB_URL=https://gitlab.example.com.

Configuración de clientes

Sección titulada «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}"
      }
    }
  }
}

Flags del modo HTTP

Sección titulada «Flags del modo HTTP»

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. Unos pocos flags —los del listener, entre ellos— no tienen equivalente en entorno:

FlagPredeterminadoDescripción
--httpfalseHabilitar modo de transporte HTTP
--http-addr:8080Direcció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-mode0660Modo 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, cargados al arrancar. Sin equivalente en entorno
--gitlab-url—URL de la instancia de GitLab. Obligatoria salvo que se pase --allow-any-gitlab-url; 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-urlfalseArranca 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 ligue una dirección de loopback o un socket unix, y aun ahí avisa al arrancar
--skip-tls-verifyfalseOmitir verificación TLS
--tool-surfacedynamicSelector canónico del catálogo: dynamic, meta o individual
--meta-param-schemaopaqueModo de schema para params de meta-herramientas: opaque, compact o full; solo afecta schemas de meta-herramientas
--capability-surfacefullSelector 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 la variable deprecada GITLAB_ENTERPRISE; no existe ningún flag --enterprise
--read-onlyfalseModo solo lectura
--safe-modefalseIntercepta herramientas modificantes y devuelve una vista previa JSON en lugar de ejecutarlas
--embedded-resourcestrueIncrustar la URI canónica del recurso MCP en los resultados get que la llevan (veintidós acciones get)
--exclude-tools—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 compleciones de argumentos que devuelven los mismos objetos
--ignore-scopesfalseOmitir detección de scopes del PAT
--max-http-clients100Número máximo de entradas (token, URL de GitLab) en el pool; acota entradas del pool, no sesiones ni peticiones simultáneas
--session-timeout30mTiempo 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
--http-idle-timeout0 (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
--statelesstrueStreamable 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-responsefalseDevolver cuerpos de respuesta application/json en lugar de text/event-stream (SSE). Sin equivalente en entorno
--max-request-body-bytes0Tamañ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-modelegacyModo de autenticación: legacy u oauth
--oauth-cache-ttl15mTTL 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 (esquema://host[:puerto][/ruta]). 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 redirect URIs). Vacío publica la página del modo servidor HTTP 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-timeout65mCancela 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-delay0Tras 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-timeout1hRecupera 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
--revalidate-interval15mIntervalo 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-rps10Lí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 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; activo por defecto porque un despliegue HTTP es compartido
--rate-limit-burst40Tamaño del token bucket cuando --rate-limit-rps > 0
--trusted-proxies—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—Cabecera HTTP con la IP real del cliente para rate limiting detrás de proxies (ej. CF-Connecting-IP, X-Forwarded-For); solo se cree desde --trusted-proxies

Flags generales (modos stdio y HTTP):

FlagPredeterminadoDescripció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 en las acciones destructivas. 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
--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
--versionfalseImprimir la versión y el commit, y salir
--shutdownfalseTerminar todas las instancias en ejecución y salir
--probefalsePreguntar 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 seis 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. Los flags de telemetría (--telemetry, --telemetry-identity, --telemetry-identity-rotation, --telemetry-tool-name) y el texto completo de --help están en la referencia CLI del repositorio.

Ejemplo:

Ventana de terminal
# 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

Sección titulada «Orden de carga de la configuración»

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

  1. ~/.gitlab-mcp-server.env — Valores predeterminados a nivel de usuario (directorio home)
  2. El archivo que nombre GITLAB_MCP_ENV_FILE — Un dotenv adicional, si el entorno nombra alguno
  3. Variables de entorno del sistema — Lo que pasó el cliente MCP, o lo que exportó el shell
  4. Flags de CLI — Argumentos de línea de comandos (prioridad más alta)

Certificados autofirmados

Sección titulada «Certificados autofirmados»

Para instancias de GitLab con certificados TLS autofirmados:

Ventana de terminal
GITLAB_MCP_SKIP_TLS_VERIFY=true

Modo solo lectura

Sección titulada «Modo solo lectura»

Habilita GITLAB_MCP_READ_ONLY=true para restringir el servidor a operaciones de solo lectura. Todas las herramientas que crean, actualizan o eliminan recursos se desactivan. 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

Sección titulada «Modo seguro»

Habilita GITLAB_MCP_SAFE_MODE=true para interceptar las herramientas de escritura y devolver una vista previa JSON estructurada de lo que se ejecutaría, sin realizar la operación. Las herramientas de solo lectura funcionan normalmente. 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 devuelven una vista previa JSON estructurada que nombra la acción canónica (por ejemplo issue.create) y los parámetros que enviaría; 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.

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.

Referencia de la fuente

Sección titulada «Referencia de la fuente»
Mantenido por GitHubLinkedInMastodonGoogle ScholarTodos los proyectos