flowchart TD
A[El servidor no arranca] --> B{Mensaje de error?}
B -->|GITLAB_TOKEN required| C[Establece GITLAB_TOKEN<br/>en .env o entorno]
B -->|Invalid GITLAB_URL| D[Corrige GITLAB_URL<br/>autogestionado]
B -->|401 Unauthorized| E[Regenera token<br/>con scope api]
B -->|403 Forbidden| F[Verifica scope api<br/>del token]
B -->|Conexión rechazada| G{GitLab accesible?}
G -->|No| H[Verifica GITLAB_URL<br/>y red]
G -->|Sí| I{Error TLS?}
I -->|Sí| J{Puedes instalar cert CA?}
J -->|Sí| J1[Añade cert CA al almacén<br/>de confianza del sistema]
J -->|No| J2[GITLAB_SKIP_TLS_VERIFY=true<br/>como último recurso]
I -->|No| K[Habilita debug logging<br/>LOG_LEVEL=debug]
style C fill:#22c55e,color:#fff
style D fill:#22c55e,color:#fff
style E fill:#22c55e,color:#fff
style F fill:#22c55e,color:#fff
style H fill:#f59e0b,color:#000
style J1 fill:#22c55e,color:#fff
style J2 fill:#f59e0b,color:#000
style K fill:#3b82f6,color:#fff
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 not a valid URL al inicio
La URL tiene sintaxis inválida
Corrige GITLAB_URL u omítela para usar https://gitlab.com en modo stdio
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
Primero intenta añadir el certificado CA al almacén de confianza del sistema. Si no es posible, 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
Si el servidor no puede resolver el hostname de tu GitLab:
Ventana de terminal
# Verificar DNS desde la máquina que ejecuta el servidor MCP
nslookupgitlab.ejemplo.com
# o
diggitlab.ejemplo.com+short
En contenedores Docker, asegúrate de que tu fichero compose o el comando docker run use --dns o una red personalizada con configuración DNS adecuada. Dentro de Kubernetes, revisa los logs de CoreDNS y resolv.conf en el pod.
El cliente MCP muestra cientos de herramientas individuales en lugar de 32
Meta-herramientas desactivadas
Establece META_TOOLS=true (por defecto) para consolidar en meta-herramientas de dominio
Herramienta no encontrada en tools/list
Desajuste de la superficie de herramientas
El modo individual usa gitlab_create_issue, el modo meta usa gitlab_issue con action: create, y el modo dinámico expone gitlab_search_tools, gitlab_describe_tools y gitlab_execute_tool
json: unknown field "<nombre>" desde una meta-herramienta
Parámetro mal escrito u obsoleto en params
Las meta-herramientas rechazan claves desconocidas. Usa los nombres exactos de la action elegida (p. ej. merge_request_iid, issue_iid, epic_iid, work_item_iid, snippet_id)
Herramientas enterprise faltantes
Catálogo enterprise desactivado
En modo stdio, establece GITLAB_ENTERPRISE=true. En modo HTTP, configura --enterprise para forzar el catálogo o deja que la autodetección CE/EE lo habilite cuando GitLab informe la edición
