feat: Token scope detection at startup with graceful degradation (#190)

polaz · semantic-release-bot · Copilot · web-flow · commit 28bab0380963 · 2026-01-24T23:09:47.000+02:00
* feat: detect token scopes at startup with graceful degradation (#188) Add TokenScopeDetector service that calls /api/v4/personal_access_tokens/self at startup to discover token scopes. Based on detected scopes: - Skip GraphQL introspection when token lacks api/read_api (no 401 stack traces) - Register only tools matching the token's permissions - Show clean INFO messages with actionable fix URLs - Warn when token expires within 7 days Also adds comprehensive authentication documentation (docs/guide/authentication.md) with PAT and OAuth walkthroughs, scope comparison table, and troubleshooting. Links added across all installation/deployment docs. * chore(release): 6.41.4 [skip ci] ## [6.41.4](v6.41.3...v6.41.4) (2026-01-24) ### Bug Fixes * **auth:** use PRIVATE-TOKEN header for PAT authentication instead of Bearer ([#189](#189)) ([7799dde](7799dde)), closes [#187](#187) * fix(auth): use enhancedFetch and UTC dates in token scope detection - Replace global fetch with enhancedFetch in detectTokenScopes and detectVersionViaREST (respects timeouts, proxy, TLS settings) - Parse expires_at as UTC date to avoid timezone off-by-one errors - Use URL/URLSearchParams for proper encoding in getTokenCreationUrl - Derive totalTools count dynamically from getToolScopeRequirements() - Use jest.useFakeTimers() for deterministic expiry tests - Test project/group token types, REST fallback, scope-gated paths * fix(auth): deduplicate getTokenCreationUrl call, remove as-any casts - Cache getTokenCreationUrl result in logTokenScopeInfo to avoid double URL construction - Replace `as any` with proper GitLabScope[] type in test fixtures * fix(token-scope): validate API response with Zod, remove manage_context from scope map Replace unsafe `as` type cast on /personal_access_tokens/self response with Zod schema validation via safeParse(). Returns null with a debug log if the response shape doesn't match expectations. Remove manage_context from TOOL_SCOPE_REQUIREMENTS since it manages local session state and never calls GitLab API — it's always available. * fix(token-scope): deep-clone scope map, preserve URL subpath, align doc counts - getToolScopeRequirements() now returns deep clone (arrays copied too) - getTokenCreationUrl() preserves subpath for self-hosted instances - Documentation updated: 43 scope-gated tools, read_user=2, read_api=23 - Example log output fixed to show URL-encoded comma (%2C) * fix(token-scope): validate scopes via z.enum, remove unreliable token type heuristic - Replace unsafe `as GitLabScope[]` cast with z.enum validation that filters unknown scopes (future GitLab scopes are silently ignored) - Derive GitLabScope type from const array via z.infer - Remove token type detection by name prefix — token names are user-controlled and cannot reliably determine token type * fix(token-scope): clarify log wording, use unknown token type, add scope filter test - Log message now says "scope-gated tools" to clarify count excludes always-available tools like manage_context - tokenType defaults to "unknown" since type cannot be reliably inferred - Add RegistryManager unit test verifying scope-based tool filtering * fix(test): update tokenType assertion to match unknown default * fix(token-scope): handle schemeless URL, fix expiry-today logic, update docs - getTokenCreationUrl() now catches URL parse errors for schemeless baseUrl and falls back to string concatenation - daysUntilExpiry === 0 now logs "expires today" instead of "has expired" - Troubleshooting docs updated to match current log format * Update src/services/ConnectionManager.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update src/services/TokenScopeDetector.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * fix(test): update schemeless URL assertion for URLSearchParams encoding --------- Co-authored-by: semantic-release-bot <semantic-release-bot@martynus.net> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -73,6 +73,7 @@ export default defineConfig({
           items: [
             { text: "Introduction", link: "/guide/" },
             { text: "Quick Start", link: "/guide/quick-start" },
+            { text: "Authentication", link: "/guide/authentication" },
           ],
         },
         {
diff --git a/docs/deployment/docker-standalone.md b/docs/deployment/docker-standalone.md
@@ -67,7 +67,7 @@ Select "standalone" when prompted for deployment type.
 |----------|----------|-------------|---------|
 | `PORT` | Yes | Internal HTTP port | — |
 | `HOST` | No | Bind address | `0.0.0.0` |
-| `GITLAB_TOKEN` | Yes | GitLab Personal Access Token | — |
+| `GITLAB_TOKEN` | Yes | [GitLab Personal Access Token](/guide/authentication#pat) | — |
 | `GITLAB_API_URL` | No | GitLab instance URL | `https://gitlab.com` |
 | `GITLAB_READ_ONLY_MODE` | No | Restrict to read-only tools | `false` |
 
diff --git a/docs/deployment/local-stdio.md b/docs/deployment/local-stdio.md
@@ -66,7 +66,7 @@ All configuration is via environment variables in the `env` object:
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `GITLAB_TOKEN` | Yes | Personal Access Token |
+| `GITLAB_TOKEN` | Yes | [Personal Access Token](/guide/authentication#pat) |
 | `GITLAB_API_URL` | No | GitLab instance URL (default: `https://gitlab.com`) |
 | `GITLAB_PROJECT_ID` | No | Default project context |
 | `GITLAB_READ_ONLY_MODE` | No | Restrict to read-only tools |
diff --git a/docs/guide/authentication.md b/docs/guide/authentication.md
@@ -0,0 +1,225 @@
+---
+title: Authentication
+description: "Choose and configure authentication for GitLab MCP Server — Personal Access Token (PAT) for local use or OAuth for team deployments"
+head:
+  - - meta
+    - name: keywords
+      content: gitlab mcp authentication, personal access token, PAT, oauth, token scopes, gitlab api token
+---
+
+# Authentication
+
+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) {#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 {#create-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 {#scopes}
+
+::: danger Required Scopes
+You MUST select `api` scope for full functionality. Without it, most tools will not work.
+:::
+
+| Scope | Required? | What it enables |
+|-------|-----------|-----------------|
+| `api` | **YES** | All 43 scope-gated tools (projects, MRs, issues, pipelines, etc.) |
+| `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`
+
+::: warning Common mistake
+Selecting only `read_user` gives access to just 2 of 43 tools (user search and events only).
+GraphQL API is completely blocked without `api` or `read_api`.
+:::
+
+### Step 4: Copy and Configure
+
+1. Click **"Create personal access token"**
+2. **Copy the token immediately** — it's shown only once!
+3. 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 {#scope-detection}
+
+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:
+
+1. **Skips GraphQL introspection** when `api` or `read_api` scope is missing (avoids 401 errors)
+2. **Registers only matching tools** — tools that would fail are not shown to the AI agent
+3. **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] Token "gitlab-mcp" has limited scopes - 2 of 43 scope-gated tools available
+[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` {#scope-comparison}
+
+| Token Scopes | Available Tools | GraphQL | REST Projects | What Works |
+|-------------|----------------|---------|---------------|------------|
+| `api, read_user` | **43/43** | Full | Full | Everything |
+| `read_api, read_user` | **23/43** | Read-only | Read-only | All browse_* tools |
+| `read_user` only | **2/43** | Blocked | Blocked | Only browse_users, browse_events |
+| `read_repository` only | **1/43** | Blocked | Blocked | Only browse_files |
+| No scopes | **0/43** | Blocked | Blocked | Nothing |
+
+## Option B: OAuth (Server/Team Deployment) {#oauth}
+
+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_SESSION_SECRET=$(openssl rand -base64 32)
+GITLAB_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_SESSION_SECRET="$(openssl rand -base64 32)" \
+  -e GITLAB_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](/guide/installation/docker)
+
+### Step 4: Add HTTPS
+
+OAuth requires HTTPS. Use a reverse proxy:
+- [TLS/HTTPS Configuration](/advanced/tls)
+- Cloudflare, nginx, Caddy, or Traefik
+
+### Step 5: Connect Clients
+
+Each user connects and authenticates individually:
+1. Add server URL to MCP client config
+2. On first use, receive a device code
+3. Enter code in GitLab to authorize
+4. Start using tools with personal identity
+
+See [OAuth details](/security/oauth) for full flow documentation.
+
+## Troubleshooting {#troubleshooting}
+
+### "GraphQL request failed: 401 Unauthorized"
+
+Your token is missing `api` or `read_api` scope. The server will show which scopes are detected:
+```
+[INFO] Token "mcp" has limited scopes - 2 of 43 scope-gated tools available
+[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
+
+The `/personal_access_tokens/self` endpoint requires GitLab 14.0+. On older versions, the server falls back to attempting operations directly.
+
+For more connection issues, see [Troubleshooting](/troubleshooting/connection).
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
@@ -11,7 +11,7 @@ Complete reference for all environment variables.
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `GITLAB_TOKEN` | GitLab personal access token | — |
+| `GITLAB_TOKEN` | [GitLab personal access token](/guide/authentication#pat) | — |
 | `GITLAB_API_URL` | GitLab instance URL | `https://gitlab.com` |
 | `GITLAB_AUTH_COOKIE_PATH` | Path to auth cookie file (cookie-based auth) | — |
 
diff --git a/docs/guide/installation/claude-desktop.md b/docs/guide/installation/claude-desktop.md
@@ -30,7 +30,7 @@ During installation, you'll be prompted for:
 
 | Setting | Required | Description |
 |---------|----------|-------------|
-| GitLab Token | Yes | Personal Access Token with `api` + `read_user` scopes |
+| GitLab Token | Yes | [Personal Access Token](/guide/authentication#pat) with `api` + `read_user` scopes |
 | GitLab URL | No | Instance URL (default: `https://gitlab.com`) |
 | Read-Only Mode | No | Disable all write operations |
 
diff --git a/docs/guide/installation/docker.md b/docs/guide/installation/docker.md
@@ -9,12 +9,14 @@ Run GitLab MCP Server as a Docker container.
 
 ## Prerequisites
 
-Before running the container, ensure you have a GitLab Personal Access Token:
+Before running the container, ensure you have a [GitLab Personal Access Token](/guide/authentication#pat):
 
 1. Go to **GitLab → Settings → Access Tokens → Personal Access Token**
 2. Create a token with `api,read_user` scopes (or `read_api,read_user` for read-only mode)
 3. Keep the token value ready — you'll pass it as `GITLAB_TOKEN` environment variable
 
+See the [Authentication Guide](/guide/authentication#scopes) for scope details and what breaks without `api`.
+
 ::: tip
 For detailed deployment options (standalone, PostgreSQL, Compose), see [Deployment](/deployment/). For guided Docker setup, run:
 ```bash
diff --git a/docs/guide/installation/index.md b/docs/guide/installation/index.md
@@ -32,7 +32,7 @@ See [Setup Wizard](/guide/installation/wizard) for a detailed walkthrough.
 ## Prerequisites
 
 - **Node.js >= 24.0.0** (for npm/npx methods)
-- **GitLab Personal Access Token** with `api` and `read_user` scopes
+- **[GitLab Personal Access Token](/guide/authentication#pat)** with `api` and `read_user` scopes
 - One or more [supported MCP clients](/clients/)
 
 ## Next Steps
diff --git a/docs/guide/installation/manual.md b/docs/guide/installation/manual.md
@@ -30,6 +30,8 @@ All MCP clients use a JSON configuration with the same structure:
 
 ### 1. Create a GitLab Token
 
+Follow the [Authentication Guide](/guide/authentication#create-token) for detailed steps, or briefly:
+
 1. Go to **Settings > Access Tokens** in your GitLab instance
 2. Create a token with `api` and `read_user` scopes
 3. Copy the token value
diff --git a/docs/guide/installation/npm.md b/docs/guide/installation/npm.md
@@ -57,7 +57,7 @@ All configuration is done via environment variables. See [Configuration](/guide/
 
 | Variable | Description |
 |----------|-------------|
-| `GITLAB_TOKEN` | GitLab personal access token with `api` scope |
+| `GITLAB_TOKEN` | [GitLab personal access token](/guide/authentication#pat) with `api` scope |
 
 ### Optional
 
diff --git a/docs/guide/quick-start.md b/docs/guide/quick-start.md
@@ -16,7 +16,11 @@ npx @structured-world/gitlab-mcp setup
 
 ## 1. Get a GitLab Token
 
-Create a [Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) with `api` and `read_user` scopes.
+Create a [Personal Access Token](/guide/authentication#pat) with `api` and `read_user` scopes.
+
+::: tip First time?
+See the [step-by-step authentication guide](/guide/authentication) for detailed instructions on token creation and scope selection.
+:::
 
 ## 2. Configure Your MCP Client
 
diff --git a/docs/guides/team-onboarding.md b/docs/guides/team-onboarding.md
@@ -32,7 +32,7 @@ See [Installation Guide](/guide/installation/npm) for detailed instructions per
 
 ### Personal Access Token
 
-Each developer needs a GitLab PAT with appropriate scopes:
+Each developer needs a [GitLab PAT](/guide/authentication#pat) with appropriate scopes:
 
 | Scope | Purpose |
 |-------|---------|
diff --git a/docs/index.md b/docs/index.md
@@ -48,7 +48,7 @@ You must configure `GITLAB_TOKEN` in your MCP client settings before the server
 ## Quick Start
 
 ::: tip Prerequisites
-Create a [GitLab Personal Access Token](https://docs.gitlab.com/user/profile/personal_access_tokens/) with `api,read_user` scopes (or `read_api,read_user` for read-only mode) and export it:
+Create a [GitLab Personal Access Token](/guide/authentication#pat) with `api,read_user` scopes (or `read_api,read_user` for read-only mode) and export it:
 ```bash
 export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
 ```
diff --git a/docs/troubleshooting/connection.md b/docs/troubleshooting/connection.md
@@ -30,6 +30,8 @@ Ensure no whitespace or newlines are included in your config.
 
 ## Scope Issues {#scopes}
 
+For detailed scope requirements, token creation steps, and what breaks without `api` scope, see the [Authentication Guide — Scope Comparison](/guide/authentication#scope-comparison).
+
 ### "403 Forbidden" on Specific Operations
 
 **Cause**: Token missing required scopes.
diff --git a/src/registry-manager.ts b/src/registry-manager.ts
@@ -59,6 +59,8 @@ import {
 } from "./config";
 import { ToolAvailability } from "./services/ToolAvailability";
 import { ConnectionManager } from "./services/ConnectionManager";
+import { isToolAvailableForScopes } from "./services/TokenScopeDetector";
+import type { GitLabScope } from "./services/TokenScopeDetector";
 import type { GitLabTier } from "./services/GitLabVersionDetector";
 import { logger } from "./logger";
 import {
@@ -296,6 +298,17 @@ class RegistryManager {
       // Connection not initialized - parameter restrictions won't apply
     }
 
+    // Pre-fetch token scope info for scope-based filtering
+    let tokenScopes: GitLabScope[] | undefined;
+    try {
+      const scopeInfo = ConnectionManager.getInstance().getTokenScopeInfo();
+      if (scopeInfo) {
+        tokenScopes = scopeInfo.scopes;
+      }
+    } catch {
+      // Connection not initialized - scope filtering won't apply
+    }
+
     for (const registry of this.registries.values()) {
       for (const [toolName, tool] of registry) {
         // Apply GITLAB_READ_ONLY_MODE filtering at registry level
@@ -310,6 +323,12 @@ class RegistryManager {
           continue;
         }
 
+        // Apply token scope filtering - skip tools the token can't access
+        if (tokenScopes && !isToolAvailableForScopes(toolName, tokenScopes)) {
+          logger.debug(`Tool '${toolName}' filtered out: insufficient token scopes`);
+          continue;
+        }
+
         // Apply GitLab version/tier filtering at registry level
         if (!ToolAvailability.isToolAvailable(toolName)) {
           const reason = ToolAvailability.getUnavailableReason(toolName);
diff --git a/src/services/ConnectionManager.ts b/src/services/ConnectionManager.ts
diff --git a/src/services/TokenScopeDetector.ts b/src/services/TokenScopeDetector.ts
diff --git a/tests/unit/RegistryManager.test.ts b/tests/unit/RegistryManager.test.ts
diff --git a/tests/unit/services/ConnectionManagerEnhanced.test.ts b/tests/unit/services/ConnectionManagerEnhanced.test.ts
diff --git a/tests/unit/services/TokenScopeDetector.test.ts b/tests/unit/services/TokenScopeDetector.test.ts

Original file line number	Diff line number	Diff line change
`@@ -73,6 +73,7 @@ export default defineConfig({`
`73`	`73`	`items: [`
`74`	`74`	`{ text: "Introduction", link: "/guide/" },`
`75`	`75`	`{ text: "Quick Start", link: "/guide/quick-start" },`
	`76`	`+ { text: "Authentication", link: "/guide/authentication" },`
`76`	`77`	`],`
`77`	`78`	`},`
`78`	`79`	`{`