This page helps you pick the right authentication method and the right transport for your environment.
The server supports four ways to authenticate against GitLab.
| Method | When to use it | Config |
|---|---|---|
| Personal Access Token | Simplest setup for local/desktop use. | GITLAB_PERSONAL_ACCESS_TOKEN |
| OAuth2 — Local Browser | Better security for local clients (Claude Desktop, VS Code). | GITLAB_USE_OAUTH=true |
| OAuth2 — MCP Proxy | Remote MCP clients such as Claude.ai. | GITLAB_MCP_OAUTH=true |
| Remote Authorization | Multi-user deployments where each caller provides their own token. | REMOTE_AUTHORIZATION=true |
!!! tip "Which one should I use?"
- **Local desktop, single user** → Personal Access Token or OAuth Local.
- **Remote single tenant (e.g., Claude.ai)** → OAuth MCP Proxy.
- **Remote multi-tenant (each user has their own GitLab token)** → Remote Authorization.
- **Docker / containers** → Personal Access Token (OAuth needs a browser).
Full guides:
- OAuth2 Setup — local browser flow & app registration.
- OAuth Callback Proxy — proxy pattern for remote clients.
- Custom Agents & Multiple PAT — multiple tokens per agent.
| Transport | When to use it |
|---|---|
| stdio | Local MCP clients (Claude Code, VS Code, Cursor, etc.). The default. |
| SSE | Legacy MCP clients that only speak Server-Sent Events. |
| Streamable HTTP | Modern remote deployments (recommended for hosted servers). |
Jump to the guide for your client:
- Claude Code
- VS Code
- GitHub Copilot
- Cursor
- Codex
- JSON-Based Clients — Factory AI Droid, OpenClaw, OpenCode, etc.
Wiki, milestones, and pipeline tools are opt-in to keep the tool list small for clients with strict tool limits. Enable what you need with environment variables or CLI flags — see Environment Variables.
If you can't use environment variables (some clients have issues with them), use CLI Arguments instead.