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 32
Meta-tools disabled
Set META_TOOLS=true (default) 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_search_tools, gitlab_describe_tools, and gitlab_execute_tool
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
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
