GitLab MCP para el homelab sin tokens globales
Conecta Claude Code, Codex o Cursor a tu GitLab autoalojado con OAuth y limita las herramientas que ven.
Por Isma4 min de lectura
El problema no es conectar, es delimitar
Tener un asistente que consulte el repositorio Laravel, una merge request o el estado de la CI puede ahorrar bastante cambio de contexto. El problema empieza cuando esa comodidad se resuelve pegando un token personal con permisos amplios en la configuración local. GitLab MCP plantea otra vía: el cliente se conecta al endpoint MCP de la instancia y autentica mediante OAuth, con los permisos del usuario que aprueba la autorización. (docs.gitlab.com)
GitLab 19.5, publicado el 15 de octubre de 2026, marca el servidor MCP como generalmente disponible para GitLab.com, GitLab Self-Managed y GitLab Dedicated. La documentación contempla clientes como Claude Code, Cursor y OpenAI Codex, todos conectados a https://<tu-gitlab>/api/v4/mcp. Para un GitLab en el homelab, esto permite que el editor o la terminal trabajen contra la instancia propia sin depender de un token API clásico con alcance api. (docs.gitlab.com)
Una conexión útil para un proyecto Laravel
La parte interesante no es pedirle al modelo que “lea todo el proyecto”, sino darle una tarea concreta. Puede revisar una merge request, buscar por qué ha fallado un pipeline, consultar metadatos del proyecto o leer un fichero concreto de los artefactos de CI. El servidor expone herramientas para repositorios, merge requests y CI, y GitLab 19.5 añade get_artifact_file para acceder a un archivo dentro de los artefactos de un job sin descargar el archivo completo. (docs.gitlab.com)
En Claude Code, la conexión HTTP no necesita un proxy adicional. El parámetro -s user hace que el servidor esté disponible para todos los proyectos del usuario, mientras que el ámbito local queda restringido al directorio desde el que se creó la configuración. Después hay que iniciar Claude Code, abrir /mcp, elegir el servidor y aprobar la autorización en el navegador. (docs.gitlab.com)
claude mcp add -s user --transport http GitLab \
https://gitlab.casa.example/api/v4/mcpEn Codex el flujo también usa HTTP, pero la documentación actual indica activar rmcp_client en ~/.codex/config.toml antes de iniciar sesión. Eso deja la autenticación en manos de codex mcp login GitLab, que abre la aprobación OAuth contra la instancia autoalojada. No hay que copiar un token de acceso personal legado: de hecho, GitLab rechaza los tokens personales clásicos, los tokens de proyecto y los de grupo para este endpoint. (docs.gitlab.com)
Menos herramientas es una configuración mejor
De serie, GitLab ofrece varios grupos de herramientas, entre ellos repository, merge_requests, work_items y ci. Para una sesión centrada en revisar código Laravel y diagnosticar pipelines, no necesito cargar el resto del catálogo. El encabezado X-Gitlab-Enabled-Mcp-Server-Toolsets acepta una lista separada por comas y permite pedir únicamente los grupos necesarios. (docs.gitlab.com)
Esta configuración es válida en clientes que aceptan un objeto headers, como Cursor. He añadido además un prefijo para evitar conflictos si uso más de una instancia GitLab o varios servidores MCP en el mismo cliente. El prefijo no concede permisos ni cambia las capacidades, solo modifica el nombre con el que el cliente ve las herramientas. (docs.gitlab.com)
{
"mcpServers": {
"GitLab homelab": {
"type": "http",
"url": "https://gitlab.casa.example/api/v4/mcp",
"headers": {
"X-Gitlab-Enabled-Mcp-Server-Toolsets": "repository,ci",
"X-Gitlab-Mcp-Server-Tool-Name-Prefix": "casa_"
}
}
}
}La letra pequeña antes de abrir el chat
Limitar los toolsets reduce las herramientas que el servidor devuelve al cliente, pero no es una frontera de autorización. Cada herramienta sigue comprobando los permisos del usuario sobre el proyecto y el espacio de nombres cuando se ejecuta. También conviene no combinar alegremente ese encabezado con X-Gitlab-Enabled-Mcp-Server-Tools: GitLab devuelve la unión de ambas listas, no la intersección. (docs.gitlab.com)
OAuth tampoco convierte el asistente en inocuo. Si autorizas una cuenta con capacidad de escribir en un proyecto, las herramientas disponibles pueden operar con esos permisos, y GitLab advierte explícitamente del riesgo de inyección de instrucciones en objetos que el modelo lee. Yo lo usaría primero en proyectos propios o de confianza, con una cuenta sin privilegios innecesarios y confirmando las acciones que modifiquen código, issues o merge requests. (docs.gitlab.com)
En una instancia con varios usuarios hay otro detalle operativo: el registro dinámico de clientes OAuth puede crear muchas aplicaciones si los clientes se conectan repetidamente. GitLab permite reutilizar una aplicación OAuth registrada previamente, aunque cada persona sigue autorizando con su propia cuenta y recibe su propio token. Si desactivas el registro dinámico, esa aplicación preconfigurada deja de ser opcional y pasa a ser necesaria. (docs.gitlab.com)