Compatibilidad

Compatibilidad con ediciones de GitLab

GitLab MCP Server funciona tanto con Community Edition (CE) como con Enterprise Edition (EE). Los tiers de pago desbloquean 17 dominios adicionales exclusivos de Enterprise, seis con Premium y el resto con Ultimate, registrados como meta-herramientas extra con GITLAB_MCP_TOOL_SURFACE=meta, herramientas gitlab_* extra con GITLAB_MCP_TOOL_SURFACE=individual y acciones extra del catálogo en la superficie dinámica predeterminada: establece GITLAB_MCP_TIER=premium (o GITLAB_MCP_TIER=ultimate) en modo stdio, usa --tier=premium/--tier=ultimate en modo HTTP, o confía en la detección, que lee la licencia de la instancia (GET /license), después los planes de los namespaces que administra el token (GET /namespaces), y recurre a free. La variable de entorno GITLAB_ENTERPRISE se eliminó en 3.0.0 y se ignora. En modo HTTP no existe ningún flag --enterprise: pasarlo aborta el arranque; usa --tier.

Funcionalidad	Community (CE)	Enterprise (EE)
Proyectos, Issues, MRs, Pipelines, CI/CD	✅	✅
Wikis, Etiquetas, Hitos, Releases	✅	✅
Usuarios, Grupos, Miembros, Búsqueda	✅	✅
Despliegues, Entornos, Paquetes	✅	✅
34 dominios base (meta-herramientas con GITLAB_MCP_TOOL_SURFACE=meta)	✅	✅
45 recursos, 37 prompts	✅	✅
Merge Trains	❌	✅
Métricas DORA	❌	✅
Gestión de vulnerabilidades	❌	✅
Eventos de auditoría	❌	✅
Políticas de cumplimiento	❌	✅
+17 dominios enterprise	❌	✅

Para habilitar funcionalidades enterprise en modo stdio, establece GITLAB_MCP_TIER=premium o GITLAB_MCP_TIER=ultimate. En modo HTTP, configura --tier=premium/--tier=ultimate para forzar el catálogo Enterprise/Premium, u omítelo para que el servidor detecte el tier por entrada token+URL, a partir de la licencia de la instancia y después de los planes de los namespaces, con free como último recurso. GITLAB_ENTERPRISE se eliminó en 3.0.0 y se ignora; no existe ningún flag --enterprise, usa --tier.

Soporte de plataformas

Hay binarios precompilados disponibles para todas las plataformas principales:

SO	Arquitectura	Binario
Linux	amd64	gitlab-mcp-server-linux-amd64
Linux	arm64	gitlab-mcp-server-linux-arm64
macOS	amd64 (Intel)	gitlab-mcp-server-darwin-amd64
macOS	arm64 (Apple Silicon)	gitlab-mcp-server-darwin-arm64
macOS	universal (arm64 + amd64)	gitlab-mcp-server-darwin-all
Windows	amd64	gitlab-mcp-server-windows-amd64.exe
Windows	arm64	gitlab-mcp-server-windows-arm64.exe

Los binarios de Linux son ejecutables independientes de posición enlazados dinámicamente y requieren glibc. En sistemas musl (Alpine), usa la imagen de contenedor ghcr.io/jmrplens/gitlab-mcp-server, que se compila contra musl dentro de la propia imagen. Desde la primera release posterior a la 2.7.5, los paquetes npm de Linux declaran libc: glibc por la misma razón y se omiten sobre musl a propósito.

Compatibilidad con clientes MCP

Cualquier cliente que soporte el transporte stdio del Model Context Protocol puede usar este servidor. Clientes probados:

Cliente	Transporte	Estado
VS Code + GitHub Copilot	stdio	✅
Claude Desktop	stdio	✅
Cursor	stdio	✅
Claude Code (CLI)	stdio	✅
Windsurf	stdio	✅
JetBrains IDEs	stdio	✅
Zed	stdio	✅
Kiro	stdio	✅
OpenAI Codex	stdio	✅
Cline (VS Code)	stdio	✅
Cualquier cliente Streamable HTTP	HTTP	✅

Perfiles de compatibilidad por cliente

Los clientes MCP están obligados a ignorar los campos que no entienden, así que el servidor envía su superficie completa a todos: iconos de herramienta, anotaciones de contenido, structuredContent, outputSchema y completions. Un sondeo de Cursor, Windsurf, Zed, Cline, Continue, VS Code Copilot, JetBrains, Gemini CLI, Goose, opencode, Crush y Claude Code no encontró ninguno que rechace un campo desconocido. La única excepción se gestiona automáticamente: las builds de Codex incluidas en ChatGPT.app rechazan resultados cuyas anotaciones de contenido llevan un valor priority fraccionario, de modo que cuando una sesión se identifica como Codex el servidor redondea esas prioridades al entero válido más cercano según la especificación. Todo lo demás (anotaciones de audiencia, contenido estructurado, esquemas de salida, iconos) se entrega sin cambios, y ningún otro cliente se ve afectado. Configura GITLAB_MCP_CLIENT_COMPAT=off para desactivar la reescritura, igual en modo stdio que en HTTP; el flag --client-compat escribe la misma variable y, cuando se pasa, prevalece sobre el entorno.

Qué cambia el perfil de Codex

• El defecto. Las builds de Codex incluidas en ChatGPT.app (verificado en codex-cli 0.148.0-alpha.9) fallan con cualquier resultado MCP cuyas anotaciones lleven un priority no entero, como 0.6, aunque la especificación admite cualquier número entre 0 y 1. rmcp, el SDK de Rust sobre el que se construye Codex, tipa bien el campo. El fallo está en la build de Codex: la unificación de features de Cargo activa arbitrary_precision de serde_json para todo el binario, así que un decimal llega al campo de coma flotante en una forma que el campo rechaza, y el resultado cae en la variante genérica de rmcp. Un 1.0 literal falla igual; solo pasan 0 y 1. Como el servidor anota su contenido Markdown con prioridades fraccionarias, cada llamada a herramienta que tenía éxito fallaba en Codex con:

  tool call error: tool call failed for `gitlab/<tool>`
  Caused by: Unexpected response type

• Detección. Codex se reconoce por lo que la sesión informa de sí misma, y nunca por la palabra “Codex” a secas:

  • Por clientInfo, siempre que la sesión lo tenga: un nombre que empiece por codex-mcp-client (en mayúsculas o minúsculas) o un título exactamente Codex, las dos formas con las que Codex se identifica desde la v0.20. Es el clientInfo que llega en initialize con el protocolo 2025-11-25 y anteriores, y el que viaja en el _meta de cada petición con 2026-07-28, así que cubre stdio en cualquiera de las dos épocas del protocolo, HTTP con --stateless=false y cualquier sesión HTTP en el protocolo 2026-07-28.
  • Por el User-Agent, solo cuando la sesión no tiene clientInfo: un valor que empiece por codex-mcp-client/ (en mayúsculas o minúsculas), que el cliente MCP de Codex envía en cada petición Streamable HTTP. Es el caso de un cliente Codex que habla el protocolo 2025-11-25 o anterior con el transporte sin estado por defecto, donde cada llamada es una sesión propia que nunca vio el initialize (issue 1043).

• Reescritura. Solo cambia priority, redondeado al entero válido más cercano según la especificación (0 o 1), en los resultados de tools/call, resources/list, resources/templates/list y prompts/get. Una prioridad redondeada a 0 se omite, porque el campo es opcional. Funciona porque Go escribe un número entero como 1 y nunca como 1.0. Las anotaciones de herramienta que lee la política de aprobación de Codex (readOnlyHint, destructiveHint) se entregan sin cambios, como todo lo demás.

• Aislamiento. Los resultados se clonan antes de reescribirlos, así que en modo HTTP la sesión de otro cliente en el mismo servidor conserva las prioridades fraccionarias exactas.

• El cliente alojado de OpenAI. Informa el clientInfo openai-mcp (Responses API) u openai-mcp (Realtime API), que ninguna de las dos reglas reconoce, y no necesita perfil: medido el 2026-09-28 (issue 1044), lee una prioridad fraccionaria sin error. Queda una etiqueta sin medir, el User-Agent openai-mcp/1.0.0 (Codex) de una llamada a herramienta desde ChatGPT en la web, y ninguna de las dos reglas lo reconoce tampoco.

Es una desviación deliberada de la especificación MCP, que dice que el clientInfo que envía un cliente “SHOULD NOT” usarse para cambiar lo que hace un servidor, y se mantiene a sabiendas (issue 959); la vuelta al User-Agent la amplía a una segunda etiqueta declarada por el propio cliente, que solo se lee cuando falta clientInfo y para ese mismo número. Cambia cómo se escribe un número y nada de lo que lee un modelo, nunca decide quién es un cliente ni qué puede hacer, porque la identidad sale de la credencial de cada petición, y se retira cuando esté ampliamente desplegada una versión de Codex construida sobre una release de rmcp con el arreglo (modelcontextprotocol/rust-sdk#1300, publicado en rmcp 3.5.0), no solo cuando se publique. Seguridad recoge esta posición junto a la otra del servidor.

El arreglo llega a los usuarios por una cadena de tres eslabones: una release de rmcp que lo incluya, que ya existe; una release de Codex construida sobre ese rmcp, que no existía en la última comprobación, el 2026-10-02 (la rama main de Codex pasó a rmcp 3.3.0 el 2026-09-30, una release sin el arreglo); y una ChatGPT.app que incluya ese Codex, cuyos usuarios no eligen su versión. La fila 17 del registro de upstream sigue cada eslabón, junto con openai/codex#38979.

Para Codex, añade el servidor a ~/.codex/config.toml con pre-aprobación de herramientas — sin ella, Codex pide confirmación en cada herramienta que no sea de solo lectura, y las ejecuciones no interactivas de codex exec cancelan esas llamadas:

~/.codex/config.toml

[mcp_servers.gitlab]
command = "/ruta/a/gitlab-mcp-server"
args = ["--transport", "stdio"]
default_tools_approval_mode = "approve"

[mcp_servers.gitlab.env]
GITLAB_URL = "https://gitlab.example.com"
GITLAB_TOKEN = "glpat-xxxxxxxxxxxxxxxxxxxx"

Límites de cliente que conviene conocer

Son restricciones de los clientes, no comportamiento del servidor. La superficie dynamic predeterminada (2 herramientas) cabe en todos los clientes de la tabla. La superficie meta (de 34 a 52 herramientas, según tier e instancia) cabe en todos salvo, quizá, en Cursor cuando el catálogo pasa de 40 (41 herramientas en GitLab.com Premium, 51 en Ultimate autoalojado), porque ese límite cuenta juntas las herramientas de todos los servidores activados. La superficie individual solo conviene a clientes sin límite de herramientas.

Cliente	Límite
Cursor	40 herramientas entre todos los servidores activados, según su documentación y su personal en 2025; su documentación actual no indica ningún límite
Windsurf	100 herramientas en total
Clientes basados en OpenAI (Codex, Copilot CLI, VS Code Copilot con modelos GPT)	128 herramientas por petición al modelo
Codex	Recorta en silencio los esquemas de herramienta de más de ~5 KB, así que deja GITLAB_MCP_META_PARAM_SCHEMA en su valor por defecto opaque; cuando un resultado lleva structuredContent, los bloques content que lo acompañan no llegan al modelo (openai/codex#10334)
Gemini CLI	Nombra cada herramienta mcp_<server>_<tool> (con __ entre servidor y herramienta antes de 0.34.0) y acorta un nombre de más de 63 caracteres sustituyendo su parte central por ...
JetBrains AI Assistant	Rechaza la respuesta entera de tools/list cuando el outputSchema de alguna herramienta tiene un tipo raíz distinto de object (LLM-30555)

Validadores de pasarelas MCP

Una pasarela (gateway) MCP valida el catálogo de un servidor antes de admitirlo, con reglas que decide su operador. Una pasarela en producción (IBM mcp-context-forge desde v1.0.0-BETA-1 hasta v1.0.0-RC2) rechazaba cualquier herramienta cuya descripción contuviera un punto y coma, y rechazaba el catálogo entero con:

All N tools failed validation ... Description contains unsafe characters

El servidor responde en dos frentes. Mantiene limpio su propio texto: todo lo que sirven tools/list (en cualquier superficie), prompts/list, resources/list y resources/templates/list es prosa en ASCII puro sin puntos y coma, incluidas las descripciones incrustadas en los esquemas, porque un validador que rechaza “caracteres inseguros” suele comparar con una clase de caracteres, y una clase resiste la siguiente regla mejor que una lista de codepoints. make check-gateway-chars lo comprueba en CI, y desde una copia del repositorio go run ./cmd/audit_gateway_chars/ imprime cada carácter problemático con su contexto. La regla cubre solo ese catálogo listado: los cuerpos de los prompts y los resultados de las herramientas no se someten a ella, y el Markdown de los resultados lleva emojis y puntos y coma. La siguiente regla la puedes cumplir tú sin esperar a una versión: GITLAB_MCP_DESCRIPTION_SUBSTITUTIONS (flag --description-substitutions, en los dos transportes) reescribe el texto listado a la salida.

Recibe pares old=new separados por comas, aplicados en orden. Una barra invertida escapa una coma, un signo igual o una barra invertida literales en cualquiera de las dos mitades, y cualquier otro escape hace que el valor se rechace. Los espacios cuentan:

# Sustituye cada punto y coma por un punto
GITLAB_MCP_DESCRIPTION_SUBSTITUTIONS=';=.'

# Sustituye los puntos y coma por comas (la coma debe escaparse)
GITLAB_MCP_DESCRIPTION_SUBSTITUTIONS=';=\,'

# Dos sustituciones en orden: "; " pasa a ". " y después ":" pasa a "-"
GITLAB_MCP_DESCRIPTION_SUBSTITUTIONS='; =. ,:=-'

La reescritura cubre lo que valida una pasarela y nada más: descripciones, títulos y títulos de anotación de las herramientas, las claves description y title incrustadas en los esquemas de entrada y de salida, y las descripciones y títulos de prompts, argumentos de prompt, recursos y plantillas de recursos. Los nombres, URIs, restricciones de esquema (pattern, const, valores de enum, defaults) y los resultados de llamadas a herramientas no se tocan nunca. Un valor mal formado impide arrancar el servidor en lugar de servir un catálogo sin reescribir a la pasarela para la que se configuró, y lo mismo ocurre con un valor de más de 32 pares o con una mitad de más de 256 bytes. Una reescritura que dejaría un texto más largo que el doble de su longitud, o que su longitud más 512 bytes cuando esa cifra es mayor, no se aplica a ese texto, que se sirve tal cual y se avisa una vez con un WARN; una configuración activa también se anuncia una vez con un WARN, porque un catálogo reescrito no se distingue de cualquier otro.

Para comprobar que una configuración elimina todos los caracteres que conoce la auditoría, ejecútala desde una copia del repositorio con las sustituciones aplicadas; termina con un código distinto de cero mientras se siga sirviendo alguno:

GITLAB_MCP_DESCRIPTION_SUBSTITUTIONS=';=.' go run ./cmd/audit_gateway_chars/ -apply -check

Si tu pasarela es mcp-context-forge, v1.0.0-RC-3 o posterior quita el punto y coma de la lista por defecto de la regla en el lado de la pasarela (issue 3770, corregido por el PR 3916). Su ajuste TOOL_DESCRIPTION_FORBIDDEN_PATTERNS, nuevo en esa versión, afina la regla, y VALIDATION_STRICT=false convierte un rechazo en un aviso en el log. El chart de Helm del proyecto (charts/mcp-stack/values.yaml) y su docker-compose.yml siguen fijando TOOL_DESCRIPTION_FORBIDDEN_PATTERNS a una lista que contiene ;, así que una pasarela desplegada con cualquiera de los dos sigue rechazando los puntos y coma hasta que sustituyas ese valor. Pasarelas MCP cubre el resto de lo que implica ejecutar el servidor detrás de una.

Funcionalidades del protocolo MCP

Además de las herramientas, GitLab MCP Server sirve las otras dos primitivas de MCP, recursos y prompts, e implementa las 4 capacidades MCP: autocompletado, elicitación, notificaciones de progreso y suscripciones a recursos. Los clientes compatibles obtienen datos contextuales, plantillas de prompts, autocompletado de argumentos, formularios interactivos y notificaciones de cambio en vivo además de las llamadas a herramientas. Los recuentos de recursos y prompts y las suscripciones son los de la superficie de capacidades full, la predeterminada; GITLAB_MCP_CAPABILITY_SURFACE=minimal conserva las herramientas, el autocompletado, el progreso, la elicitación y el manifiesto gitlab://tools. Los iconos se adjuntan a cada herramienta, recurso y prompt como metadatos, no como una capacidad.

Capacidad	Soportada
Herramientas	✅ (hasta 1088 autoalojadas Enterprise / 1094 GitLab.com + Orbit individuales / 34 base, 51 autoalojadas, 52 GitLab.com meta)
Recursos	✅ (45)
Prompts	✅ (37)
Autocompletado	✅ (18 nombres de argumento)
Elicitación	✅
Progreso	✅
Suscripciones	✅ (26 tipos de recurso, atendidas mediante sondeo)

Las cifras de 1088 autoalojadas y 1094 en GitLab.com son el conjunto expandido de instancias de herramienta distintas. Los recuentos de 34 base, 51 autoalojadas y 52 en GitLab.com son tamaños del catálogo de meta-herramientas cuyas acciones se expanden a esa superficie individual mayor.

Lectura adicional

• Configuración: el ajuste del tier, las variables de entorno y todos los demás ajustes
• Configuración de clientes: dónde guarda cada cliente la entrada del servidor y qué lleva

Preguntas frecuentes

¿GitLab MCP Server funciona con GitLab Community Edition?

Sí. GitLab MCP Server funciona tanto con Community Edition (CE) como con Enterprise Edition (EE). En CE expone el catálogo base completo — 34 meta-herramientas base, 45 recursos y 37 prompts — que cubre proyectos, issues, merge requests, pipelines, CI/CD, wikis, releases, usuarios, grupos, búsqueda, despliegues, entornos y paquetes. Las funcionalidades exclusivas de Enterprise como merge trains, métricas DORA, gestión de vulnerabilidades, eventos de auditoría y políticas de cumplimiento requieren una licencia Premium o Ultimate y no están disponibles en CE.

¿Cómo habilito las herramientas Enterprise?

Define el tier de licencia explícitamente o deja que el servidor lo autodetecte. En modo stdio, establece GITLAB_MCP_TIER=premium o GITLAB_MCP_TIER=ultimate; en modo HTTP pasa --tier=premium o --tier=ultimate. Cuando se omite el tier, el servidor lo detecta a partir de la licencia de la instancia (GET /license) y después de los planes de los namespaces que administra el token (GET /namespaces), con free como último recurso; en modo HTTP lo hace por entrada token+URL. En una instancia autoalojada, forzar Premium lleva el número de meta-herramientas de 34 a 40, y Ultimate lo lleva a 51. La variable de entorno GITLAB_ENTERPRISE se eliminó en 3.0.0 y se ignora. En modo HTTP no existe ningún flag --enterprise: pasarlo aborta el arranque; usa --tier.

¿Qué sistemas operativos y arquitecturas se admiten?

Hay binarios precompilados disponibles para Linux, macOS y Windows en amd64 y arm64 — seis binarios en total, más una build universal de macOS, gitlab-mcp-server-darwin-all, que funciona en ambas arquitecturas. macOS ofrece compilaciones separadas para Intel (amd64) y Apple Silicon (arm64). Cada plataforma se distribuye como un único binario autocontenido: no hay que instalar runtime de Go, intérprete ni bibliotecas aparte. Los binarios de Linux son ejecutables independientes de posición que usan el cargador dinámico de glibc, así que necesitan un userland con glibc; en distribuciones musl como Alpine, usa la imagen de contenedor ghcr.io/jmrplens/gitlab-mcp-server, compilada contra musl.

¿Funciona GitLab MCP Server con OpenAI Codex?

Sí. El servidor detecta las sesiones de Codex automáticamente y aplica un perfil de compatibilidad: las prioridades de las anotaciones de contenido se redondean a valores enteros, que es lo que exigen las builds de Codex incluidas en ChatGPT.app, mientras que el resto de campos se entrega sin cambios. Configura el servidor en ~/.codex/config.toml con default_tools_approval_mode = "approve" para que las ejecuciones no interactivas puedan usar herramientas de escritura, y mantén la superficie de herramientas dynamic por defecto. Usa GITLAB_MCP_CLIENT_COMPAT=off para desactivar la reescritura por cliente.

¿Qué clientes MCP son compatibles con GitLab MCP Server?

Cualquier cliente que soporte el Model Context Protocol puede usar GitLab MCP Server. Los clientes stdio probados incluyen VS Code + GitHub Copilot, Claude Desktop, Cursor, Claude Code (CLI), Windsurf, IDEs de JetBrains, Zed, Kiro, OpenAI Codex y Cline. Cualquier cliente Streamable HTTP puede conectarse mediante el modo HTTP. El servidor también admite recursos MCP (45), prompts (37), autocompletado (18 nombres de argumento), elicitación, notificaciones de progreso y suscripciones a recursos (notificaciones de cambio en vivo para 26 tipos de recurso).