flowchart TD
A[Server won't start] --> B{Error message?}
B -->|GITLAB_TOKEN required| C[Set GITLAB_TOKEN<br/>in .env or env]
B -->|Invalid GITLAB_URL| D[Fix self-managed<br/>GITLAB_URL]
B -->|401 Unauthorized| E[Regenerate token<br/>with api scope]
B -->|403 Forbidden| F[Check token has<br/>api scope]
B -->|Connection refused| G{Is GitLab reachable?}
G -->|No| H[Check GITLAB_URL<br/>and network]
G -->|Yes| I{TLS error?}
I -->|Yes| J{Can install CA cert?}
J -->|Yes| J1[Add CA cert to system<br/>trust store]
J -->|No| J2[Set GITLAB_SKIP_TLS_VERIFY=true<br/>as last resort]
I -->|No| K[Enable 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
Symptom
Cause
Solution
GITLAB_TOKEN is required at startup
Token not set
Set GITLAB_TOKEN in .env or environment
GITLAB_URL is not a valid URL at startup
URL has invalid syntax
Fix GITLAB_URL or omit it to use https://gitlab.com in stdio mode
401 Unauthorized from GitLab API
Invalid or expired PAT
Generate a new token with api scope at GitLab → Preferences → Access Tokens
403 Forbidden on specific operations
Token lacks required scope
Ensure the token has api scope (not just read_api)
Connection refused or timeout
GitLab instance unreachable
Verify GITLAB_URL is reachable: curl -s $GITLAB_URL/api/v4/version
First try adding the CA certificate to your system trust store. If that’s not possible, set GITLAB_SKIP_TLS_VERIFY=true in .env or --skip-tls-verify in HTTP mode
x509: certificate has expired
Expired TLS certificate
Renew the certificate on the GitLab server, or use GITLAB_SKIP_TLS_VERIFY=true temporarily
If the server cannot resolve your GitLab hostname:
Terminal window
# Verify DNS from the machine running the MCP server
nslookupgitlab.example.com
# or
diggitlab.example.com+short
In Docker containers, ensure your compose file or docker run command uses --dns or a custom network with proper DNS configuration. Inside Kubernetes, check CoreDNS logs and resolv.conf in the pod.
MCP client shows hundreds of individual tools instead of 33
Individual surface selected
Set TOOL_SURFACE=meta to consolidate into domain meta-tools
Tool not found in tools/list
Tool surface mismatch
Individual mode uses gitlab_create_issue, meta mode uses gitlab_issue with action: create, and dynamic mode exposes gitlab_find_action and gitlab_execute_action
Meta-tools reject unknown keys. Use the exact parameter names for the chosen action (e.g. merge_request_iid, issue_iid, epic_iid, work_item_iid, snippet_id)
Enterprise tools missing
Enterprise catalog disabled
In stdio mode, set GITLAB_ENTERPRISE=true. In HTTP mode, set --enterprise to force the catalog or let CE/EE auto-detection enable it when GitLab reports edition
Send PRIVATE-TOKEN or Authorization: Bearer <token> header with every request
Pool eviction too frequent
Too many unique tokens
Increase --max-http-clients (default: 100)
Sessions expiring unexpectedly
MCP idle timeout too short
Increase --session-timeout (default: 30m)
MCP sessions drop every ~2 min / keepalive ping failed; closing session
A low --http-idle-timeout (or a proxy timeout) is closing long-lived SSE streams
Default --http-idle-timeout=0 disables HTTP-layer idle closure; if you set a low value, raise it or use 0. Behind a reverse proxy, also raise its read/idle timeout
Run Ctrl+Shift+P → MCP: List Servers to verify configuration
”Permission denied” on startup
Run chmod +x /path/to/gitlab-mcp-server (Linux/macOS)
Server restarts repeatedly
Check MCP Logs for missing GITLAB_URL or GITLAB_TOKEN
Waiting for initialize with Docker logs showing HTTP mode
Add --http=false after the image name for stdio mode (JSON-RPC over stdin/stdout, no port needed). Alternatively, run the container in HTTP mode with -p 8080:8080 and configure the MCP client as HTTP pointing to http://host:8080/mcp — this only works if the server is running and the port is reachable.
Symptom
Solution
Tools not listed
Verify .cursor/mcp.json exists and uses mcpServers key (not servers)
${input:...} not working
Not supported by Cursor — use environment variables instead
