Compatibilidad

Compatibilidad con ediciones de GitLab

GitLab MCP Server funciona tanto con Community Edition (CE) como con Enterprise Edition (EE). El catálogo Enterprise/Premium desbloquea 17 dominios adicionales exclusivos de Enterprise, 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 autodetección desde GET /license (por defecto free). La variable de entorno GITLAB_ENTERPRISE=true, ya deprecada, se sigue respetando cuando GITLAB_MCP_TIER no está definida (equivale a ultimate) y deja un aviso en el log. 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 autodetecte CE/EE por entrada token+URL cuando GitLab informe la edición. La variable deprecada GITLAB_ENTERPRISE=true sigue funcionando cuando GITLAB_MCP_TIER no está definida; 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	✅
Cualquier cliente Streamable HTTP	HTTP	✅

Perfiles de compatibilidad por cliente

La mayoría de los clientes ignoran los campos MCP que no entienden, así que el servidor envía su superficie completa a todos. 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.

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"

Mantén la superficie de herramientas dynamic por defecto para clientes con límites de número de herramientas (Cursor limita cada servidor a 40 herramientas, Windsurf a 100, los clientes basados en OpenAI a 128 por petición) y deja GITLAB_MCP_META_PARAM_SCHEMA en su valor por defecto opaque para Codex, que recorta silenciosamente los esquemas de herramienta mayores de ~5 KB.

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 antes de 0.7.0) rechazaba cualquier descripción de herramienta que contuviera un punto y coma. El servidor mantiene todo lo que lista en ASCII puro y sin puntos y coma, en todas las superficies (una clase de caracteres resiste la siguiente regla mejor que una lista de codepoints), y un mecanismo de sustituciones permite a un despliegue cumplir una regla nueva de pasarela sin esperar a una versión:

# Reescribe descripciones y títulos listados: pares old=new separados por
# comas, aplicados en orden (la barra invertida escapa \, \= \\)
GITLAB_MCP_DESCRIPTION_SUBSTITUTIONS=';=.'

La reescritura cubre descripciones y títulos de herramientas, prompts, recursos y plantillas de recursos, incluidas las descripciones incrustadas en los esquemas de herramienta. Los nombres, URIs, restricciones de esquema (pattern, const, valores de enum, defaults) y los resultados de llamadas a herramientas no se tocan nunca, y un valor mal formado impide arrancar el servidor en lugar de servir un catálogo sin reescribir. Si tu pasarela es mcp-context-forge, actualizar a 0.7.0 o posterior también resuelve el rechazo del punto y coma en el lado de la pasarela (issue 3770).

Funcionalidades del protocolo MCP

GitLab MCP Server implementa el conjunto completo de capacidades MCP más allá de las herramientas — recursos, prompts, completions, elicitation, notificaciones de progreso y suscripciones a recursos — para que los clientes compatibles obtengan datos contextuales, plantillas de prompts, autocompletado de argumentos y notificaciones de cambio en vivo además de las llamadas a herramientas.

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

Las cifras de 1085 autoalojadas y 1091 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.

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 autodetecta la edición desde GET /license por entrada token+URL, con valor por defecto free. Forzar el catálogo Enterprise/Premium lleva el número de meta-herramientas de 34 a 51. La variable de entorno GITLAB_ENTERPRISE=true, ya deprecada, se sigue respetando cuando GITLAB_MCP_TIER no está definida (equivale a ultimate) y deja un aviso en el log. 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 y Kiro. Cualquier cliente Streamable HTTP puede conectarse mediante el modo HTTP. El servidor también admite recursos MCP (45), prompts (37), completions (18 tipos de argumento), elicitation, notificaciones de progreso y suscripciones a recursos (notificaciones de cambio en vivo para 26 tipos de recurso).

Referencia de la fuente

Documentación para desarrolladores

Esta página es la matriz de compatibilidad orientada a usuarios. Para flags de tier, variables de entorno y configuración por cliente, consulta docs/reference/configuration.