| Síntoma | Causa | Solución |
|---|
GITLAB_TOKEN is required al inicio | Token no establecido | Establece GITLAB_TOKEN en .env o en el entorno |
GITLAB_URL is required al inicio | URL no establecida | Establece GITLAB_URL en .env o usa el flag --gitlab-url |
401 Unauthorized de la API de GitLab | PAT inválido o expirado | Genera un nuevo token con scope api en GitLab → Preferences → Access Tokens |
403 Forbidden en operaciones específicas | El token carece del scope requerido | Asegúrate de que el token tiene scope api (no solo read_api) |
| Conexión rechazada o timeout | Instancia de GitLab inaccesible | Verifica que GITLAB_URL es accesible: curl -s $GITLAB_URL/api/v4/version |
| Síntoma | Causa | Solución |
|---|
x509: certificate signed by unknown authority | Certificado autofirmado | Establece GITLAB_SKIP_TLS_VERIFY=true en .env o --skip-tls-verify en modo HTTP |
x509: certificate has expired | Certificado TLS expirado | Renueva el certificado en el servidor de GitLab, o usa GITLAB_SKIP_TLS_VERIFY=true temporalmente |
| Síntoma | Causa | Solución |
|---|
| El cliente MCP muestra 1006 herramientas en lugar de 42 | Meta-herramientas desactivadas | Establece META_TOOLS=true (por defecto) para consolidar en meta-herramientas de dominio |
Herramienta no encontrada en tools/list | Desajuste del modo de meta-herramientas | El modo individual usa gitlab_create_issue, el modo meta usa gitlab_issue con action: create |
unknown action en llamada a meta-herramienta | Parámetro de acción inválido | Verifica las acciones válidas en Resumen de Herramientas |
| Herramientas enterprise faltantes | Modo enterprise desactivado | Establece GITLAB_ENTERPRISE=true para habilitar 15 meta-herramientas enterprise adicionales |
| Síntoma | Causa | Solución |
|---|
| Actualización detectada pero no aplicada | Modo es solo check | Establece AUTO_UPDATE=true para habilitar la aplicación automática |
| Sigue ejecutando la versión antigua tras la actualización | Proceso no reiniciado (Windows) | Reinicia el servidor o usa gitlab-mcp-server --shutdown para terminar todas las instancias |
| No se puede reemplazar el binario (archivo bloqueado) | Las instancias en ejecución mantienen el archivo | Ejecuta gitlab-mcp-server --shutdown para terminar todas las instancias primero |
| Error de red alcanzando GitHub | Firewall o proxy bloqueando | Verifica la conectividad a github.com desde el servidor |
| Síntoma | Causa | Solución |
|---|
400 Bad Request | Cabecera de token faltante | Envía la cabecera PRIVATE-TOKEN o Authorization: Bearer <token> con cada solicitud |
| Desalojo del pool demasiado frecuente | Demasiados tokens únicos | Aumenta --max-http-clients (por defecto: 100) |
| Sesiones expirando inesperadamente | Timeout de inactividad muy corto | Aumenta --session-timeout (por defecto: 30m) |
| Síntoma | Causa | Solución |
|---|
401 Unauthorized con token OAuth válido | Token expirado o rechazado por GitLab | Re-autoriza a través del flujo OAuth; verifica que la aplicación OAuth de GitLab siga activa |
| Alta latencia en la primera solicitud tras expirar la caché | Re-validación del token contra la API de GitLab | Comportamiento esperado — aumenta --oauth-cache-ttl (por defecto: 15m, máx: 2h) para reducir la frecuencia de validación |
404 en /.well-known/oauth-protected-resource | Modo OAuth no habilitado | Inicia el servidor con --auth-mode=oauth |
| El cliente no inicia el flujo OAuth | El cliente no soporta OAuth 2.1 | Usa la cabecera PRIVATE-TOKEN en su lugar — funciona en modo OAuth mediante normalización automática |
La cabecera PRIVATE-TOKEN no funciona en modo OAuth | Debería funcionar | El middleware normaliza PRIVATE-TOKEN a Bearer — verifica la validez del token |
Operaciones fallan con scope mcp insuficiente | DCR fallback asignó scope mcp en lugar de api | Configura clientId explícitamente en la configuración del cliente MCP. Ver Modo servidor HTTP |
| Síntoma | Causa | Solución |
|---|
| Resultados de listas truncados | Límite predeterminado de per_page | Pasa los parámetros per_page (máx 100) y page para paginar |
nextPage faltante en la respuesta | Última página alcanzada | No hay más resultados — este es el comportamiento esperado |
| Síntoma | Solución |
|---|
| ”Tool not found” en Copilot Chat | Verifica el panel de Salida → MCP Logs para errores. Verifica la ruta de .vscode/mcp.json |
| El servidor no aparece en el estado MCP | Ejecuta Ctrl+Shift+P → MCP: List Servers para verificar la configuración |
| ”Permission denied” al inicio | Ejecuta chmod +x /ruta/al/gitlab-mcp-server (Linux/macOS) |
| El servidor se reinicia repetidamente | Verifica MCP Logs por GITLAB_URL o GITLAB_TOKEN faltantes |
| Síntoma | Solución |
|---|
| Las herramientas no se listan | Verifica que .cursor/mcp.json existe y usa la clave mcpServers (no servers) |
${input:...} no funciona | No es soportado por Cursor — usa variables de entorno en su lugar |
Habilita el registro detallado para diagnosticar problemas:
LOG_LEVEL=debug ./gitlab-mcp-server 2>debug.log
# Modo HTTP (logs mezclados con la salida del servidor)
LOG_LEVEL=debug ./gitlab-mcp-server --http --gitlab-url=https://gitlab.ejemplo.com 2>debug.log
Los logs de depuración incluyen:
- Cada llamada a herramienta con parámetros de entrada
- Detalles de solicitud/respuesta de la API de GitLab
- Eventos de validación de token (solo los últimos 4 caracteres)
- Operaciones del pool de sesiones (modo HTTP)
Si no puedes resolver un problema:
- Habilita el registro de depuración (
LOG_LEVEL=debug) y captura la salida
- Revisa las GitHub Issues para problemas conocidos
- Abre una nueva issue con:
- Versión del servidor (
gitlab-mcp-server --version o revisa los logs de inicio)
- Sistema operativo y arquitectura
- Nombre y versión del cliente MCP
- Logs de depuración redactados (elimina cualquier token o dato sensible)
- Pasos para reproducir el problema
