GitLab MCP Authentication Guide

GitLab MCP Server supports two authentication modes. Choose based on your use case.

Which mode do I need?

Use Case	Mode	Why
Personal local use (Claude Code, Cursor, etc.)	PAT	Simple, one token in config
CI/CD pipelines, automation	PAT	No user interaction needed
Shared server for a team	OAuth	Per-user identity, audit trail
Docker/cloud deployment	OAuth	No shared secrets, token rotation
Claude.ai Custom Connector	OAuth	Required by Claude.ai

Option A: Personal Access Token (PAT)

Best for: individual developers running gitlab-mcp locally.

Step 1: Open Token Settings in GitLab

Navigate to your GitLab instance:

GitLab.com:https://gitlab.com/-/user_settings/personal_access_tokens

Self-hosted:https://your-gitlab.com/-/user_settings/personal_access_tokens

Or via UI: Avatar (top-left) → Edit profile → Access tokens (left sidebar)

Step 2: Create the Token

Field	Value	Notes
Token name	`gitlab-mcp`	Any descriptive name
Expiration date	90 days recommended	GitLab enforces max 365 days
Select scopes	See table below

Step 3: Select Scopes

Required Scopes

You MUST select api scope for full functionality. Without it, most tools will not work.

Scope	Required?	What it enables
`api`	YES	GitLab read and write operations permitted by your account and instance
`read_user`	Recommended	User info display, avatar, email
`read_api`	Alternative	Read-only access (use with `GITLAB_READ_ONLY_MODE=true`)
`read_repository`	Optional	File content access (covered by `api`)
`write_repository`	Optional	File mutations (covered by `api`)

Minimum for full functionality: api + read_user

Minimum for read-only: read_api + read_user

Common mistake

Selecting only read_user leaves most GitLab operations unavailable. GraphQL API is completely blocked without api or read_api.

Step 4: Copy and Configure

Click "Create personal access token"
Copy the token immediately — it's shown only once!
Token format: glpat-xxxxxxxxxxxxxxxxxxxx

Add to your MCP client config:

json

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@structured-world/gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "glpat-your-token-here",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

Scope Detection at Startup

GitLab MCP Server automatically detects your token's scopes at startup using the /api/v4/personal_access_tokens/self endpoint. Based on the detected scopes, the server:

Skips GraphQL introspection when api or read_api scope is missing (avoids 401 errors)
Registers only matching tools — tools that would fail are not shown to the AI agent
Shows a clear message explaining what's available and how to fix it

What you see with limited scopes

With full access (api + read_user):

[INFO] Token "gitlab-mcp" detected (scopes: api, read_user)

With limited access (read_user only):

[INFO] GraphQL introspection skipped (requires 'api' or 'read_api' scope)
[INFO] For full functionality, create a token with 'api' scope:
       https://gitlab.com/-/user_settings/personal_access_tokens?name=gitlab-mcp&scopes=api%2Cread_user

Token expiry warnings

When your token expires within 7 days:

[WARN] Token "gitlab-mcp" expires in 3 day(s)

Scope Comparison: What Breaks Without `api`

Token Scopes	Available Tools	GraphQL	REST Projects	What Works
`api, read_user`	Account- and instance-dependent	Full	Full	Reads and writes permitted by GitLab
`read_api, read_user`	Read access	Read-only	Read-only	Read operations permitted by GitLab
`read_user` only	Limited user-related access	Blocked	Blocked	Matching REST operations
`read_repository` only	Limited repository access	Blocked	Blocked	Matching file operations
No scopes	Setup helpers remain available	Blocked	Blocked	Configure or reconnect the server

The complete catalog contains 66 tools; 39 can be used in server read-only mode, including helpers that change local settings rather than GitLab data. Token scopes, version, tier, feature flags and account settings can reduce the available catalog further. Scope coverage does not guarantee that every action of an otherwise visible tool is permitted by GitLab.

Option B: OAuth (Server/Team Deployment)

Best for: shared servers, Docker deployments, team access.

With OAuth, each user authenticates with their own GitLab identity — no shared tokens.

Step 1: Create GitLab OAuth Application

Navigate to: GitLab → User Settings → Applications (or Admin → Applications for instance-wide)

Field	Value
Name	`GitLab MCP Server`
Redirect URI	`https://your-mcp-server.com/oauth/callback`
Confidential	No (PKCE provides security)
Scopes	`api` and `read_user`

Click Save application and copy the Application ID.

Step 2: Configure Server Environment

bash

# Required
OAUTH_ENABLED=true
OAUTH_ISSUER=https://your-mcp-server.com   # public URL clients connect to
OAUTH_SESSION_SECRET=$(openssl rand -base64 32)
OAUTH_CLIENT_ID=your-application-id
GITLAB_API_URL=https://gitlab.com

# Server
PORT=3333
HOST=0.0.0.0

Step 3: Deploy

Docker:

bash

docker run -d --name gitlab-mcp \
  -e OAUTH_ENABLED=true \
  -e OAUTH_ISSUER=https://your-mcp-server.com \
  -e OAUTH_SESSION_SECRET="$(openssl rand -base64 32)" \
  -e OAUTH_CLIENT_ID=your-app-id \
  -e GITLAB_API_URL=https://gitlab.com \
  -e PORT=3333 \
  -p 3333:3333 \
  ghcr.io/structured-world/gitlab-mcp:latest

Docker Compose: See Docker Compose deployment

Step 4: Add HTTPS

OAuth requires HTTPS. Use a reverse proxy:

TLS/HTTPS Configuration
Cloudflare, nginx, Caddy, or Traefik

Step 5: Connect Clients

Each user connects and authenticates individually:

Add server URL to MCP client config
On first use, receive a device code
Enter code in GitLab to authorize
Start using tools with personal identity

See OAuth details for full flow documentation.

Troubleshooting

"GraphQL request failed: 401 Unauthorized"

Your token is missing api or read_api scope. The server will show which scopes are detected:

[INFO] GraphQL introspection skipped (requires 'api' or 'read_api' scope)

Fix: Create a new token with api + read_user scopes.

"403 Forbidden" on specific operations

Token has read_api but not api. Write operations (create, update, delete) need api scope.

Token expired

Tokens have an expiration date. Check in GitLab → Settings → Access Tokens. The server warns when a token expires within 7 days.

Scope detection not working

Scope detection uses the /personal_access_tokens/self endpoint, available on every supported GitLab version (16.0+). If it fails, the server falls back to attempting operations directly.

For more connection issues, see Troubleshooting.

GitLab MCP Authentication Guide ​

Which mode do I need? ​

Option A: Personal Access Token (PAT) ​

Step 1: Open Token Settings in GitLab ​

Step 2: Create the Token ​

Step 3: Select Scopes ​

Step 4: Copy and Configure ​

Scope Detection at Startup ​

What you see with limited scopes ​

Token expiry warnings ​

Scope Comparison: What Breaks Without api ​

Option B: OAuth (Server/Team Deployment) ​

Step 1: Create GitLab OAuth Application ​

Step 2: Configure Server Environment ​

Step 3: Deploy ​

Step 4: Add HTTPS ​

Step 5: Connect Clients ​

Troubleshooting ​

"GraphQL request failed: 401 Unauthorized" ​

"403 Forbidden" on specific operations ​

Token expired ​

Scope detection not working ​