@zereight/mcp-gitlab 2.0.35 → 2.0.36

package/README.md

@@ -16,10 +16,17 @@ When using with the Claude App, you need to set up your API key and URLs directl
 
 #### Authentication Methods
 
-The server supports two authentication methods:
+The server supports four authentication methods:
 
-1. **Personal Access Token** (traditional method)
-2. **OAuth2** (recommended for better security)
+**For local/desktop use** (most common):
+
+1. **Personal Access Token** (`GITLAB_PERSONAL_ACCESS_TOKEN`) — simplest setup
+2. **OAuth2 — Local Browser** (`GITLAB_USE_OAUTH`) — recommended for better security
+
+**For server/remote deployments**:
+
+3. **OAuth2 — MCP Proxy** (`GITLAB_MCP_OAUTH`) — for remote MCP clients such as Claude.ai
+4. **Remote Authorization** (`REMOTE_AUTHORIZATION`) — multi-user deployments where each caller provides their own token
 
 #### Using OAuth2 Authentication
 
@@ -325,6 +332,89 @@ docker run -i --rm \
 }
 ```
 
+#### Using MCP OAuth Proxy (`GITLAB_MCP_OAUTH`)
+
+> **For server/remote deployments only.** This mode requires the MCP server to be deployed with a publicly accessible HTTPS URL. For local/desktop use, see `GITLAB_USE_OAUTH` above.
+
+For remote MCP clients that support the MCP OAuth specification (e.g. Claude.ai).
+The server acts as a full OAuth 2.0 authorization server — unauthenticated requests
+receive a `401 + WWW-Authenticate` response, which triggers the OAuth browser flow
+automatically on the client side.
+
+**How it works**: You deploy this MCP server somewhere with a public HTTPS URL. MCP
+clients connect to `{MCP_SERVER_URL}/mcp`. The server handles the OAuth 2.0 flow,
+exchanging credentials with GitLab on behalf of the client.
+
+**Prerequisites**:
+
+1. A publicly accessible HTTPS server URL (`MCP_SERVER_URL`) — use [ngrok](https://ngrok.com) for local testing
+2. A pre-registered GitLab OAuth application with `api` (or `read_api`) scopes
+   — Go to `Admin area` → `Applications`, set Redirect URI to `{MCP_SERVER_URL}/callback`
+
+| Environment Variable  | Required | Description                                                |
+| --------------------- | -------- | ---------------------------------------------------------- |
+| `GITLAB_MCP_OAUTH`    | ✅       | Set to `true` to enable                                    |
+| `GITLAB_API_URL`      | ✅       | GitLab API base URL                                        |
+| `GITLAB_OAUTH_APP_ID` | ✅       | GitLab OAuth Application ID                                |
+| `MCP_SERVER_URL`      | ✅       | Public HTTPS URL of this MCP server                        |
+| `STREAMABLE_HTTP`     | ✅       | Must be `true`                                             |
+| `GITLAB_OAUTH_SCOPES` | optional | Comma-separated scopes (default: `api,read_api,read_user`) |
+
+```shell
+docker run -i --rm \
+  -e HOST=0.0.0.0 \
+  -e GITLAB_MCP_OAUTH=true \
+  -e STREAMABLE_HTTP=true \
+  -e MCP_SERVER_URL=https://your-server.example.com \
+  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
+  -e GITLAB_OAUTH_APP_ID=your_app_id \
+  -p 3000:3002 \
+  zereight050/gitlab-mcp
+```
+
+MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "type": "http",
+      "url": "https://your-server.example.com/mcp"
+    }
+  }
+}
+```
+
+#### Using Remote Authorization (`REMOTE_AUTHORIZATION`)
+
+> **For server/remote deployments only.** Each HTTP caller provides their own GitLab token directly in request headers — no OAuth flow involved.
+
+For multi-user or multi-tenant deployments where each caller provides their own
+GitLab token in the HTTP request header. No OAuth flow — the MCP server forwards
+the token to GitLab on behalf of the caller.
+
+**Header priority**: `Private-Token` > `JOB-TOKEN` > `Authorization: Bearer`
+
+| Environment Variable     | Required | Description                                                |
+| ------------------------ | -------- | ---------------------------------------------------------- |
+| `REMOTE_AUTHORIZATION`   | ✅       | Set to `true` to enable                                    |
+| `STREAMABLE_HTTP`        | ✅       | Must be `true`                                             |
+| `ENABLE_DYNAMIC_API_URL` | optional | Allow per-request GitLab URL via `X-GitLab-API-URL` header |
+
+**Example request headers**:
+
+```http
+Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx
+```
+
+or using a Bearer token:
+
+```http
+Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx
+```
+
+> ⚠️ `REMOTE_AUTHORIZATION` is **not compatible** with SSE transport. `STREAMABLE_HTTP=true` is required.
+
 ### Environment Variables
 
 #### Authentication Configuration
@@ -342,6 +432,9 @@ docker run -i --rm \
   - **SSE transport is disabled** - attempting to use SSE with remote authorization will cause the server to exit with an error
   - Each client session can use a different token, enabling multi-user support with secure session isolation
   - Tokens are stored per session and automatically cleaned up when sessions close or timeout
+- `GITLAB_MCP_OAUTH`: Set to `true` to enable the server-side MCP OAuth proxy mode. See [MCP OAuth Setup](#mcp-oauth-setup-claudeai-native-oauth) for details.
+- `GITLAB_OAUTH_APP_ID`: Client ID of the pre-registered GitLab OAuth application. Required when `GITLAB_MCP_OAUTH=true`.
+- `GITLAB_OAUTH_SCOPES`: Comma-separated list of GitLab scopes to request during the MCP OAuth flow (e.g. `api,read_user`). Defaults to `api` (or `read_api` when `GITLAB_READ_ONLY_MODE=true`). Only used when `GITLAB_MCP_OAUTH=true`. The pre-registered application must be configured with at least these scopes.
 - `SESSION_TIMEOUT_SECONDS`: Session auth token timeout in seconds. Default: `3600` (1 hour). Valid range: 1-86400 seconds (recommended: 60+). After this period of inactivity, the auth token is removed but the transport session remains active. The client must provide auth headers again on the next request. Only applies when `REMOTE_AUTHORIZATION=true`.
 
 #### General Configuration
@@ -357,6 +450,7 @@ docker run -i --rm \
 - `USE_MILESTONE`: Legacy flag. Milestone features are now enabled by default. When set to 'true', ensures milestone-related tools are included even if the `milestones` toolset is not explicitly listed in `GITLAB_TOOLSETS`.
 - `USE_PIPELINE`: Legacy flag. Pipeline features are now enabled by default. When set to 'true', ensures pipeline-related tools are included even if the `pipelines` toolset is not explicitly listed in `GITLAB_TOOLSETS`.
 - `GITLAB_TOOLSETS`: Comma-separated list of toolset IDs to enable. When empty or unset, default toolsets are used. Set to `"all"` to enable every toolset. Available toolsets (default toolsets marked with `*`):
+
   - `merge_requests`\* — MR operations, notes, discussions, draft notes, threads, versions, file diffs, conflicts (34 tools)
   - `issues`\* — Issue CRUD, notes, links, discussions (14 tools)
   - `repositories`\* — Search, create, file contents, push, fork, tree (7 tools)
@@ -375,11 +469,13 @@ docker run -i --rm \
   Note: `execute_graphql` is not in any toolset and must be added individually via `GITLAB_TOOLS` if needed.
   Exposing arbitrary GraphQL would allow bypassing toolset boundaries (e.g. querying data that the user intentionally disabled via toolsets like wiki or pipelines), which is a security and permission-containment concern. Keeping `execute_graphql` out of all toolsets and requiring explicit opt-in via `GITLAB_TOOLS=execute_graphql` is intentional, to align with that principle rather than for backward compatibility.
   CLI arg: `--toolsets`
+
 - `GITLAB_TOOLS`: Comma-separated list of individual tool names to add on top of the enabled toolsets (additive). Useful for cherry-picking specific tools without enabling an entire toolset. Example: `GITLAB_TOOLS="list_pipelines,execute_graphql"`. CLI arg: `--tools`
 
   Combined logic: `final tools = (tools from enabled toolsets) ∪ (GITLAB_TOOLS) ∪ (legacy flag overrides)`
 
   Examples:
+
   ```bash
   # Default behavior (unchanged)
   GITLAB_PERSONAL_ACCESS_TOKEN=xxx npx @zereight/mcp-gitlab
@@ -399,6 +495,7 @@ docker run -i --rm \
   # Legacy flags still work (backward compatible)
   USE_PIPELINE=true npx @zereight/mcp-gitlab
   ```
+
 - `GITLAB_AUTH_COOKIE_PATH`: Path to an authentication cookie file for GitLab instances that require cookie-based authentication. When provided, the cookie will be included in all GitLab API requests.
 - `SSE`: When set to 'true', enables the Server-Sent Events transport.
 - `STREAMABLE_HTTP`: When set to 'true', enables the Streamable HTTP transport. If both **SSE** and **STREAMABLE_HTTP** are set to 'true', the server will prioritize Streamable HTTP over SSE transport.
@@ -512,7 +609,7 @@ calls (need `api` or `read_api`).
 1. Go to your GitLab instance → **Admin Area > Applications** (instance-wide) or **User Settings > Applications** (personal)
 2. Create a new application with:
    - **Confidential**: unchecked
-   - **Scopes**: `api`, `read_api`, `read_user`
+   - **Scopes**: `api`, `read_api`, `read_user` (or whichever scopes you intend to request via `GITLAB_OAUTH_SCOPES`)
 3. Save and copy the **Application ID** — this is your `GITLAB_OAUTH_APP_ID`
 
 **How it works:**
@@ -566,14 +663,15 @@ No `headers` field is needed — Claude.ai obtains the token via OAuth automatic
 
 **Environment variables:**
 
-| Variable | Required | Description |
-|---|---|---|
-| `GITLAB_MCP_OAUTH` | Yes | Set to `true` to enable |
-| `GITLAB_OAUTH_APP_ID` | Yes | Client ID of the pre-registered GitLab OAuth application |
-| `MCP_SERVER_URL` | Yes | Public HTTPS URL of your MCP server |
-| `GITLAB_API_URL` | Yes | Your GitLab instance API URL (e.g. `https://gitlab.com/api/v4`) |
-| `STREAMABLE_HTTP` | Yes | Must be `true` (SSE is not supported) |
-| `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | No | Set `true` for local HTTP dev only |
+| Variable                                    | Required | Description                                                                                                                                                                                                         |
+| ------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GITLAB_MCP_OAUTH`                          | Yes      | Set to `true` to enable                                                                                                                                                                                             |
+| `GITLAB_OAUTH_APP_ID`                       | Yes      | Client ID of the pre-registered GitLab OAuth application                                                                                                                                                            |
+| `MCP_SERVER_URL`                            | Yes      | Public HTTPS URL of your MCP server                                                                                                                                                                                 |
+| `GITLAB_API_URL`                            | Yes      | Your GitLab instance API URL (e.g. `https://gitlab.com/api/v4`)                                                                                                                                                     |
+| `STREAMABLE_HTTP`                           | Yes      | Must be `true` (SSE is not supported)                                                                                                                                                                               |
+| `GITLAB_OAUTH_SCOPES`                       | No       | Comma-separated GitLab scopes to request (e.g. `api,read_user`). Defaults to `api` (or `read_api` when `GITLAB_READ_ONLY_MODE=true`). The pre-registered application must be configured with at least these scopes. |
+| `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | No       | Set `true` for local HTTP dev only                                                                                                                                                                                  |
 
 **Important Notes:**
 
@@ -582,6 +680,11 @@ No `headers` field is needed — Claude.ai obtains the token via OAuth automatic
 - Session timeout, rate limiting, and capacity limits apply identically to the
   `REMOTE_AUTHORIZATION` mode (`SESSION_TIMEOUT_SECONDS`, `MAX_REQUESTS_PER_MINUTE`,
   `MAX_SESSIONS`)
+- **Header auth fallback:** when `Private-Token` or `JOB-TOKEN` request headers are
+  present, OAuth validation is skipped and the raw token is used directly for that
+  session. This allows PATs and CI job tokens to be used alongside the OAuth flow on
+  the same server instance. `Authorization: Bearer` is always treated as an OAuth
+  token — use `Private-Token` for PAT-based header auth.
 
 ## Tools 🛠️
 

package/build/index.js

@@ -155,7 +155,7 @@ function createServer() {
         // Manually retrieve the session context using the session ID passed in the request.
         // This is a robust workaround for AsyncLocalStorage context loss.
         const sessionId = request.params.sessionId;
-        if (REMOTE_AUTHORIZATION && sessionId && authBySession[sessionId]) {
+        if ((REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) && sessionId && authBySession[sessionId]) {
             const authData = authBySession[sessionId];
             const sessionContext = {
                 sessionId,
@@ -343,6 +343,10 @@ const REMOTE_AUTHORIZATION = getConfig("remote-auth", "REMOTE_AUTHORIZATION") ==
 const GITLAB_MCP_OAUTH = getConfig("mcp-oauth", "GITLAB_MCP_OAUTH") === "true";
 const MCP_SERVER_URL = getConfig("mcp-server-url", "MCP_SERVER_URL");
 const GITLAB_OAUTH_APP_ID = getConfig("oauth-app-id", "GITLAB_OAUTH_APP_ID");
+const GITLAB_OAUTH_SCOPES_RAW = getConfig("oauth-scopes", "GITLAB_OAUTH_SCOPES");
+const GITLAB_OAUTH_SCOPES = GITLAB_OAUTH_SCOPES_RAW
+    ? GITLAB_OAUTH_SCOPES_RAW.split(",").map((s) => s.trim()).filter(Boolean)
+    : undefined;
 const ENABLE_DYNAMIC_API_URL = getConfig("enable-dynamic-api-url", "ENABLE_DYNAMIC_API_URL") === "true";
 const SESSION_TIMEOUT_SECONDS = Number.parseInt(getConfig("session-timeout", "SESSION_TIMEOUT_SECONDS", "3600"), 10);
 const HOST = getConfig("host", "HOST") || "127.0.0.1";
@@ -532,11 +536,10 @@ function buildAuthHeaders() {
         }
         return {}; // No auth headers if no session context
     }
-    // CI job tokens use a dedicated header (not Bearer/Private-Token)
-    if (GITLAB_JOB_TOKEN) {
-        return { "JOB-TOKEN": String(GITLAB_JOB_TOKEN) };
-    }
-    // Standard mode: prioritize OAuth token, then fall back to environment token
+    // Standard mode: PAT preferred over job token (broader permissions).
+    // OAuth token takes priority over PAT when both are set.
+    // NOTE: Changed in PR #400 — previously GITLAB_JOB_TOKEN had highest priority.
+    // If both GITLAB_PERSONAL_ACCESS_TOKEN and GITLAB_JOB_TOKEN are set, PAT wins.
     const token = OAUTH_ACCESS_TOKEN || GITLAB_PERSONAL_ACCESS_TOKEN;
     if (IS_OLD && token) {
         return { "Private-Token": String(token) };
@@ -544,6 +547,10 @@ function buildAuthHeaders() {
     if (token) {
         return { Authorization: `Bearer ${token}` };
     }
+    // Fall back to CI job token
+    if (GITLAB_JOB_TOKEN) {
+        return { "JOB-TOKEN": String(GITLAB_JOB_TOKEN) };
+    }
     return {};
 }
 /**
@@ -854,7 +861,7 @@ const allTools = [
     },
     {
         name: "create_issue_note",
-        description: "Add a new note to an existing issue thread",
+        description: "Add a note to an issue. Creates a top-level comment, or replies to a discussion thread if discussion_id is provided",
         inputSchema: toJSONSchema(CreateIssueNoteSchema),
     },
     {
@@ -1833,7 +1840,7 @@ if (GITLAB_MCP_OAUTH) {
         logger.error("Set STREAMABLE_HTTP=true to enable MCP OAuth");
         process.exit(1);
     }
-    logger.info("MCP OAuth enabled: GitLab OAuth proxy active");
+    logger.info("MCP OAuth enabled: GitLab OAuth proxy active (Private-Token/JOB-TOKEN headers bypass OAuth)");
 }
 if (!REMOTE_AUTHORIZATION && !GITLAB_MCP_OAUTH && !USE_OAUTH && !GITLAB_PERSONAL_ACCESS_TOKEN && !GITLAB_JOB_TOKEN && !GITLAB_AUTH_COOKIE_PATH) {
     // Standard mode: token must be in environment (unless using OAuth)
@@ -3836,14 +3843,17 @@ async function updateIssueNote(projectId, issueIid, discussionId, noteId, body,
  * Create a note in an issue discussion
  * @param {string} projectId - The ID or URL-encoded path of the project
  * @param {number} issueIid - The IID of an issue
- * @param {string} discussionId - The ID of a thread
+ * @param {string} [discussionId] - The ID of a thread (omit for top-level note)
  * @param {string} body - The content of the new note
  * @param {string} [createdAt] - The creation date of the note (ISO 8601 format)
  * @returns {Promise<GitLabDiscussionNote>} The created note
  */
 async function createIssueNote(projectId, issueIid, discussionId, body, createdAt) {
     projectId = decodeURIComponent(projectId); // Decode project ID
-    const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/issues/${issueIid}/discussions/${discussionId}/notes`);
+    const basePath = `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/issues/${issueIid}`;
+    const url = new URL(discussionId
+        ? `${basePath}/discussions/${discussionId}/notes`
+        : `${basePath}/notes`);
     const payload = { body };
     if (createdAt) {
         payload.created_at = createdAt;
@@ -8464,10 +8474,19 @@ async function startStreamableHTTPServer() {
         session.count++;
         return true;
     };
+    /**
+     * Check whether the request carries a raw header auth token (Private-Token or JOB-TOKEN).
+     * Used to decide whether to bypass OAuth validation.
+     */
+    const hasHeaderAuth = (req) => {
+        return !!(req.headers["private-token"] ||
+            req.headers["job-token"]);
+    };
     /**
      * Parse authentication from request headers
      * Returns null if no auth found or invalid format
-     * Supports: JOB-TOKEN header, Private-Token header, Authorization Bearer header
+     * Supports: Private-Token header, JOB-TOKEN header, Authorization Bearer header
+     * Priority: Private-Token > JOB-TOKEN > Authorization Bearer
      */
     const parseAuthHeaders = (req) => {
         const authHeader = req.headers["authorization"] || "";
@@ -8486,17 +8505,18 @@ async function startStreamableHTTPServer() {
                 return null; // Reject if URL is malformed
             }
         }
-        // Extract token
+        // Extract token — priority: Private-Token > JOB-TOKEN > Authorization Bearer
+        // PATs are preferred over job tokens because they carry broader permissions.
         let token = null;
         let header = null;
-        if (jobToken) {
-            token = jobToken.trim();
-            header = "JOB-TOKEN";
-        }
-        else if (privateToken) {
+        if (privateToken) {
             token = privateToken.trim();
             header = "Private-Token";
         }
+        else if (jobToken) {
+            token = jobToken.trim();
+            header = "JOB-TOKEN";
+        }
         else if (authHeader) {
             // Use \S+ instead of .+ to prevent ReDoS attacks
             // \S+ only matches non-whitespace, so trim() is technically unnecessary,
@@ -8557,7 +8577,7 @@ async function startStreamableHTTPServer() {
         app.set("trust proxy", 1);
         const gitlabBaseUrl = GITLAB_API_URL.replace(/\/api\/v4\/?$/, "").replace(/\/$/, "");
         const issuerUrl = new URL(MCP_SERVER_URL);
-        const oauthProvider = createGitLabOAuthProvider(gitlabBaseUrl, GITLAB_OAUTH_APP_ID, "GitLab MCP Server", GITLAB_READ_ONLY_MODE);
+        const oauthProvider = createGitLabOAuthProvider(gitlabBaseUrl, GITLAB_OAUTH_APP_ID, "GitLab MCP Server", GITLAB_READ_ONLY_MODE, GITLAB_OAUTH_SCOPES);
         // Mounts /.well-known/oauth-authorization-server,
         //        /.well-known/oauth-protected-resource,
         //        /authorize, /token, /register, /revoke
@@ -8565,7 +8585,7 @@ async function startStreamableHTTPServer() {
             provider: oauthProvider,
             issuerUrl,
             baseUrl: issuerUrl,
-            scopesSupported: ["api", "read_api", "read_user"],
+            scopesSupported: GITLAB_OAUTH_SCOPES ?? ["api", "read_api", "read_user"],
             resourceName: "GitLab MCP Server",
         }));
         // Expose provider so the /mcp route middleware can reference it
@@ -8574,11 +8594,36 @@ async function startStreamableHTTPServer() {
     // Build bearer-auth middleware — no-op unless GITLAB_MCP_OAUTH is enabled.
     // Unauthenticated requests receive 401 + WWW-Authenticate header, which is
     // exactly what Claude.ai needs to trigger the OAuth browser flow.
-    const mcpBearerAuth = GITLAB_MCP_OAUTH
+    //
+    // Header auth fallback: if Private-Token or JOB-TOKEN headers are present,
+    // OAuth validation is skipped and the raw token is used directly per-session.
+    // Note: Authorization: Bearer is always treated as an OAuth token and goes
+    // through OAuth validation — use Private-Token for PAT-based header auth.
+    const oauthBearerAuth = GITLAB_MCP_OAUTH
         ? requireBearerAuth({
             verifier: app._mcpOAuthProvider,
             requiredScopes: [],
         })
+        : undefined;
+    const mcpBearerAuth = GITLAB_MCP_OAUTH
+        ? (req, res, next) => {
+            const privateToken = req.headers["private-token"] || "";
+            const jobToken = req.headers["job-token"] || "";
+            if (privateToken || jobToken) {
+                // Validate the raw token before bypassing OAuth
+                const authData = parseAuthHeaders(req);
+                if (authData) {
+                    next();
+                    return;
+                }
+                res.status(401).json({
+                    error: "Invalid Private-Token or JOB-TOKEN header",
+                    message: "The provided token failed validation. Check the token value and format.",
+                });
+                return;
+            }
+            oauthBearerAuth(req, res, next);
+        }
         : (_req, _res, next) => next();
     // Streamable HTTP endpoint - handles both session creation and message handling
     app.post("/mcp", mcpBearerAuth, async (req, res) => {
@@ -8611,8 +8656,8 @@ async function startStreamableHTTPServer() {
                 if (!authData) {
                     metrics.authFailures++;
                     res.status(401).json({
-                        error: "Missing Authorization, Private-Token, or JOB-TOKEN header",
-                        message: "Remote authorization is enabled. Please provide Authorization, Private-Token, or JOB-TOKEN header.",
+                        error: "Missing Private-Token, JOB-TOKEN, or Authorization header",
+                        message: "Remote authorization is enabled. Please provide Private-Token, JOB-TOKEN, or Authorization header.",
                     });
                     return;
                 }
@@ -8636,28 +8681,49 @@ async function startStreamableHTTPServer() {
                 // First request without session - will fail in initialization
             }
         }
-        // MCP OAuth mode — token already validated by requireBearerAuth middleware.
-        // req.auth is populated by the middleware; store/refresh per session so that
-        // buildAuthHeaders() can pick it up via AsyncLocalStorage, exactly like the
-        // REMOTE_AUTHORIZATION path.
+        // MCP OAuth mode — either header auth (PAT/job token) or OAuth Bearer token.
+        // Header auth takes precedence: if Private-Token or JOB-TOKEN is present the
+        // OAuth middleware was bypassed and we store the raw token per-session.
+        // Otherwise req.auth is populated by requireBearerAuth; store the OAuth token.
         if (GITLAB_MCP_OAUTH) {
-            const authInfo = req.auth;
-            if (authInfo?.token && sessionId) {
-                if (!authBySession[sessionId]) {
-                    authBySession[sessionId] = {
-                        header: "Authorization",
-                        token: authInfo.token,
-                        lastUsed: Date.now(),
-                        apiUrl: GITLAB_API_URL,
-                    };
-                    logger.info(`Session ${sessionId}: stored OAuth token (client: ${authInfo.clientId})`);
-                    setAuthTimeout(sessionId);
+            const headerAuthData = hasHeaderAuth(req) ? parseAuthHeaders(req) : null;
+            if (headerAuthData) {
+                if (headerAuthData && sessionId) {
+                    if (!authBySession[sessionId]) {
+                        authBySession[sessionId] = headerAuthData;
+                        logger.info(`Session ${sessionId}: stored ${headerAuthData.header} header (header auth)`);
+                        setAuthTimeout(sessionId);
+                    }
+                    else {
+                        authBySession[sessionId] = {
+                            ...authBySession[sessionId],
+                            header: headerAuthData.header,
+                            token: headerAuthData.token,
+                            lastUsed: Date.now(),
+                        };
+                        setAuthTimeout(sessionId);
+                    }
                 }
-                else {
-                    // Update token on every request — the client may have refreshed it
-                    authBySession[sessionId].token = authInfo.token;
-                    authBySession[sessionId].lastUsed = Date.now();
-                    setAuthTimeout(sessionId);
+            }
+            else {
+                const authInfo = req.auth;
+                if (authInfo?.token && sessionId) {
+                    if (!authBySession[sessionId]) {
+                        authBySession[sessionId] = {
+                            header: "Authorization",
+                            token: authInfo.token,
+                            lastUsed: Date.now(),
+                            apiUrl: GITLAB_API_URL,
+                        };
+                        logger.info(`Session ${sessionId}: stored OAuth token (client: ${authInfo.clientId})`);
+                        setAuthTimeout(sessionId);
+                    }
+                    else {
+                        // Update token on every request — the client may have refreshed it
+                        authBySession[sessionId].token = authInfo.token;
+                        authBySession[sessionId].lastUsed = Date.now();
+                        setAuthTimeout(sessionId);
+                    }
                 }
             }
         }
@@ -8688,18 +8754,29 @@ async function startStreamableHTTPServer() {
                                     setAuthTimeout(newSessionId);
                                 }
                             }
-                            // Store OAuth token for newly created session in MCP OAuth mode
+                            // Store OAuth token for newly created session in MCP OAuth mode.
+                            // If Private-Token or JOB-TOKEN headers are present, prefer them.
                             if (GITLAB_MCP_OAUTH && !authBySession[newSessionId]) {
-                                const authInfo = req.auth;
-                                if (authInfo?.token) {
-                                    authBySession[newSessionId] = {
-                                        header: "Authorization",
-                                        token: authInfo.token,
-                                        lastUsed: Date.now(),
-                                        apiUrl: GITLAB_API_URL,
-                                    };
-                                    logger.info(`Session ${newSessionId}: stored OAuth token (client: ${authInfo.clientId})`);
-                                    setAuthTimeout(newSessionId);
+                                if (hasHeaderAuth(req)) {
+                                    const authData = parseAuthHeaders(req);
+                                    if (authData) {
+                                        authBySession[newSessionId] = authData;
+                                        logger.info(`Session ${newSessionId}: stored ${authData.header} header (header auth)`);
+                                        setAuthTimeout(newSessionId);
+                                    }
+                                }
+                                else {
+                                    const authInfo = req.auth;
+                                    if (authInfo?.token) {
+                                        authBySession[newSessionId] = {
+                                            header: "Authorization",
+                                            token: authInfo.token,
+                                            lastUsed: Date.now(),
+                                            apiUrl: GITLAB_API_URL,
+                                        };
+                                        logger.info(`Session ${newSessionId}: stored OAuth token (client: ${authInfo.clientId})`);
+                                        setAuthTimeout(newSessionId);
+                                    }
                                 }
                             }
                         },

package/build/oauth-proxy.js

@@ -82,11 +82,16 @@ class GitLabOAuthServerProvider {
     _resourceName;
     _requiredScopes;
     _clientCache = new BoundedClientCache(CLIENT_CACHE_MAX_SIZE);
-    constructor(gitlabBaseUrl, gitlabAppId, resourceName, readOnly) {
+    constructor(gitlabBaseUrl, gitlabAppId, resourceName, readOnly, customScopes) {
         this._gitlabBaseUrl = gitlabBaseUrl;
         this._gitlabAppId = gitlabAppId;
         this._resourceName = resourceName;
-        this._requiredScopes = readOnly ? REQUIRED_GITLAB_SCOPES_RO : REQUIRED_GITLAB_SCOPES_RW;
+        this._requiredScopes =
+            customScopes && customScopes.length > 0
+                ? customScopes
+                : readOnly
+                    ? REQUIRED_GITLAB_SCOPES_RO
+                    : REQUIRED_GITLAB_SCOPES_RW;
     }
     // ---- Client store (local DCR) ------------------------------------------
     get clientsStore() {
@@ -251,7 +256,9 @@ class GitLabOAuthServerProvider {
  * @param gitlabBaseUrl  Root URL of the GitLab instance (no trailing slash, no /api/v4).
  * @param gitlabAppId    Client ID of the pre-registered GitLab OAuth application.
  * @param resourceName   Human-readable name shown on the GitLab consent screen.
+ * @param readOnly       When true and customScopes is not set, restricts to read_api scope.
+ * @param customScopes   Explicit list of GitLab scopes to require. Overrides readOnly when set.
  */
-export function createGitLabOAuthProvider(gitlabBaseUrl, gitlabAppId, resourceName = "GitLab MCP Server", readOnly = false) {
-    return new GitLabOAuthServerProvider(gitlabBaseUrl, gitlabAppId, resourceName, readOnly);
+export function createGitLabOAuthProvider(gitlabBaseUrl, gitlabAppId, resourceName = "GitLab MCP Server", readOnly = false, customScopes) {
+    return new GitLabOAuthServerProvider(gitlabBaseUrl, gitlabAppId, resourceName, readOnly, customScopes);
 }

package/build/schemas.js

@@ -1116,10 +1116,10 @@ export const UpdateIssueNoteSchema = ProjectParamsSchema.extend({
     .refine(data => !(data.body !== undefined && data.resolved !== undefined), {
     message: "Only one of 'body' or 'resolved' can be provided, not both",
 });
-// Input schema for adding a note to an existing issue discussion
+// Input schema for adding a note to an issue (top-level comment or discussion reply)
 export const CreateIssueNoteSchema = ProjectParamsSchema.extend({
     issue_iid: z.coerce.string().describe("The IID of an issue"),
-    discussion_id: z.coerce.string().describe("The ID of a thread"),
+    discussion_id: z.coerce.string().optional().describe("The ID of a thread. If provided, replies to that thread; otherwise creates a top-level note"),
     body: z.string().describe("The content of the note or reply"),
     created_at: z.string().optional().describe("Date the note was created at (ISO 8601 format)"),
 });

package/build/test/mcp-oauth-tests.js

@@ -15,6 +15,8 @@ import { MockGitLabServer, findMockServerPort } from "./utils/mock-gitlab-server
 // ---------------------------------------------------------------------------
 const MOCK_OAUTH_TOKEN = "ya29.mock-oauth-token-abcdef123456";
 const MOCK_CLIENT_ID = "mock-app-uid-from-dcr";
+const MOCK_PAT_TOKEN = "glpat-mockpat-testtoken-abcdef12"; // ≥20 chars, valid charset
+const MOCK_JOB_TOKEN = "mockjobtoken-testenv-1234567890"; // ≥20 chars, valid charset
 const MOCK_GITLAB_PORT_BASE = 9200;
 const MCP_SERVER_PORT_BASE = 3200;
 // ---------------------------------------------------------------------------
@@ -441,3 +443,110 @@ describe("MCP OAuth — createGitLabOAuthProvider", () => {
         console.log(`  ✓ client_name annotated: ${registered.client_name}`);
     });
 });
+// ---------------------------------------------------------------------------
+// Test suite: Header auth fallback within GITLAB_MCP_OAUTH mode
+// ---------------------------------------------------------------------------
+describe("MCP OAuth — Header Auth Fallback", () => {
+    let mcpUrl;
+    let mcpBaseUrl;
+    let mockGitLab;
+    let servers = [];
+    before(async () => {
+        const mockPort = await findMockServerPort(MOCK_GITLAB_PORT_BASE + 150);
+        mockGitLab = new MockGitLabServer({
+            port: mockPort,
+            // Include both OAuth token and raw tokens so GitLab API calls succeed
+            validTokens: [MOCK_OAUTH_TOKEN, MOCK_PAT_TOKEN, MOCK_JOB_TOKEN],
+        });
+        await mockGitLab.start();
+        const mockGitLabUrl = mockGitLab.getUrl();
+        // OAuth endpoints needed for server startup AS metadata
+        addOAuthEndpoints(mockGitLab, MOCK_OAUTH_TOKEN, MOCK_CLIENT_ID, mockGitLabUrl);
+        const mcpPort = await findAvailablePort(MCP_SERVER_PORT_BASE + 150);
+        mcpBaseUrl = `http://${HOST}:${mcpPort}`;
+        mcpUrl = `${mcpBaseUrl}/mcp`;
+        const server = await launchServer({
+            mode: TransportMode.STREAMABLE_HTTP,
+            port: mcpPort,
+            timeout: 5000,
+            env: {
+                STREAMABLE_HTTP: "true",
+                GITLAB_MCP_OAUTH: "true",
+                GITLAB_OAUTH_APP_ID: "test-oauth-app-id",
+                GITLAB_API_URL: `${mockGitLabUrl}/api/v4`,
+                MCP_SERVER_URL: mcpBaseUrl,
+                MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL: "true",
+            },
+        });
+        servers.push(server);
+        console.log(`Mock GitLab (header-auth): ${mockGitLabUrl}`);
+        console.log(`MCP Server  (header-auth): ${mcpBaseUrl}`);
+    });
+    after(async () => {
+        cleanupServers(servers);
+        if (mockGitLab) {
+            await mockGitLab.stop();
+        }
+    });
+    const initBody = JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+            protocolVersion: "2024-11-05",
+            capabilities: {},
+            clientInfo: { name: "test-client", version: "1.0.0" },
+        },
+    });
+    test("POST /mcp with Private-Token header bypasses OAuth and is accepted", async () => {
+        const res = await fetch(mcpUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+                "Private-Token": MOCK_PAT_TOKEN,
+            },
+            body: initBody,
+        });
+        assert.notStrictEqual(res.status, 401, "Should not return 401 with valid Private-Token");
+        assert.notStrictEqual(res.status, 403, "Should not return 403 with valid Private-Token");
+        console.log(`  ✓ Private-Token header accepted (status: ${res.status})`);
+    });
+    test("POST /mcp with JOB-TOKEN header bypasses OAuth and is accepted", async () => {
+        const res = await fetch(mcpUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+                "job-token": MOCK_JOB_TOKEN,
+            },
+            body: initBody,
+        });
+        assert.notStrictEqual(res.status, 401, "Should not return 401 with valid JOB-TOKEN");
+        assert.notStrictEqual(res.status, 403, "Should not return 403 with valid JOB-TOKEN");
+        console.log(`  ✓ JOB-TOKEN header accepted (status: ${res.status})`);
+    });
+    test("POST /mcp with valid OAuth Bearer token still works normally", async () => {
+        const res = await fetch(mcpUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+                Authorization: `Bearer ${MOCK_OAUTH_TOKEN}`,
+            },
+            body: initBody,
+        });
+        assert.notStrictEqual(res.status, 401, "OAuth Bearer should still work alongside header auth");
+        assert.notStrictEqual(res.status, 403, "Should not return 403 with valid OAuth token");
+        console.log(`  ✓ OAuth Bearer token still accepted (status: ${res.status})`);
+    });
+    test("POST /mcp with no auth still returns 401", async () => {
+        const res = await fetch(mcpUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: initBody,
+        });
+        assert.strictEqual(res.status, 401, "Should return 401 with no auth");
+        console.log("  ✓ No auth still returns 401");
+    });
+});

package/build/test/schema-tests.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env ts-node
-import { GetFileContentsSchema, GitLabFileContentSchema, CreatePipelineSchema } from '../schemas.js';
+import { GetFileContentsSchema, GitLabFileContentSchema, CreatePipelineSchema, CreateIssueNoteSchema } from '../schemas.js';
 function runGetFileContentsSchemaTests() {
     console.log('🧪 Testing GetFileContentsSchema...');
     const cases = [
@@ -298,12 +298,86 @@ function runCreatePipelineSchemaTests() {
     console.log(`\nResults: ${passed} passed, ${failed} failed`);
     return { passed, failed };
 }
+function runCreateIssueNoteSchemaTests() {
+    console.log('\n🧪 Testing CreateIssueNoteSchema...');
+    const cases = [
+        {
+            name: 'schema:create_issue_note:top-level-note-without-discussion-id',
+            input: { project_id: 'my/project', issue_iid: '42', body: 'A comment' },
+            expected: { project_id: 'my/project', issue_iid: '42', body: 'A comment', discussion_id: undefined }
+        },
+        {
+            name: 'schema:create_issue_note:reply-with-discussion-id',
+            input: { project_id: 'my/project', issue_iid: '42', discussion_id: 'abc123', body: 'A reply' },
+            expected: { project_id: 'my/project', issue_iid: '42', discussion_id: 'abc123', body: 'A reply' }
+        },
+        {
+            name: 'schema:create_issue_note:with-created-at',
+            input: { project_id: 'my/project', issue_iid: '7', body: 'Note', created_at: '2025-01-01T00:00:00Z' },
+            expected: { project_id: 'my/project', issue_iid: '7', body: 'Note', created_at: '2025-01-01T00:00:00Z' }
+        },
+        {
+            name: 'schema:create_issue_note:numeric-issue-iid-coerced',
+            input: { project_id: 'my/project', issue_iid: 99, body: 'Coerced' },
+            expected: { project_id: 'my/project', issue_iid: '99', body: 'Coerced' }
+        },
+        {
+            name: 'schema:create_issue_note:reject-missing-body',
+            input: { project_id: 'my/project', issue_iid: '1' },
+            shouldFail: true
+        }
+    ];
+    let passed = 0;
+    let failed = 0;
+    cases.forEach(testCase => {
+        const result = {
+            name: testCase.name,
+            status: 'failed'
+        };
+        const parsed = CreateIssueNoteSchema.safeParse(testCase.input);
+        if (testCase.shouldFail) {
+            if (parsed.success) {
+                result.error = 'Expected schema validation to fail';
+            }
+            else {
+                result.status = 'passed';
+            }
+        }
+        else if (parsed.success) {
+            const expected = testCase.expected || {};
+            const matches = Object.entries(expected).every(([key, value]) => {
+                const actual = parsed.data[key];
+                return actual === value;
+            });
+            if (matches) {
+                result.status = 'passed';
+            }
+            else {
+                result.error = `Unexpected parsed result: ${JSON.stringify(parsed.data)}`;
+            }
+        }
+        else {
+            result.error = parsed.error?.message || 'Schema validation failed';
+        }
+        if (result.status === 'passed') {
+            passed++;
+            console.log(`✅ ${result.name}`);
+        }
+        else {
+            failed++;
+            console.log(`❌ ${result.name}: ${result.error}`);
+        }
+    });
+    console.log(`\nResults: ${passed} passed, ${failed} failed`);
+    return { passed, failed };
+}
 if (import.meta.url === `file://${process.argv[1]}`) {
     const getFileContentsResult = runGetFileContentsSchemaTests();
     const fileContentResult = runGitLabFileContentSchemaTests();
     const createPipelineResult = runCreatePipelineSchemaTests();
-    const totalPassed = getFileContentsResult.passed + fileContentResult.passed + createPipelineResult.passed;
-    const totalFailed = getFileContentsResult.failed + fileContentResult.failed + createPipelineResult.failed;
+    const createIssueNoteResult = runCreateIssueNoteSchemaTests();
+    const totalPassed = getFileContentsResult.passed + fileContentResult.passed + createPipelineResult.passed + createIssueNoteResult.passed;
+    const totalFailed = getFileContentsResult.failed + fileContentResult.failed + createPipelineResult.failed + createIssueNoteResult.failed;
     console.log(`\nTotal Results: ${totalPassed} passed, ${totalFailed} failed`);
     if (totalFailed > 0) {
         process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zereight/mcp-gitlab",
-  "version": "2.0.35",
+  "version": "2.0.36",
   "description": "MCP server for using the GitLab API",
   "license": "MIT",
   "author": "zereight",