feat: add MCP OAuth mode

[titouanmathis]

Problem

When deploying this MCP server for a team using a self-hosted GitLab instance, there is no way for multiple users to authenticate with their own GitLab accounts without each one manually generating a Personal Access Token and configuring it in their MCP client. This is friction-heavy, hard to manage at scale, and breaks when tokens expire.

This PR adds a GITLAB_MCP_OAUTH=true mode that enables the MCP spec OAuth flow: users authenticate directly with GitLab through their MCP client's browser flow, and tokens are managed per session on the server.

Prerequisites

A pre-registered GitLab OAuth application is required. GitLab restricts dynamically registered (unverified) applications to the mcp scope, which is insufficient for API 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
3. Save and copy the Application ID — this is your GITLAB_OAUTH_APP_ID

How it works

1. User adds the MCP server URL in their MCP client (e.g. Claude.ai)
2. Client discovers OAuth endpoints via /.well-known/oauth-authorization-server
3. Client registers itself via Dynamic Client Registration (POST /register) — handled locally by the MCP server (each client gets a virtual client ID)
4. Client redirects the user's browser to GitLab's login page using the pre-registered OAuth application
5. User authenticates; GitLab redirects back to the client's callback URL
6. Client sends Authorization: Bearer <token> on every MCP request
7. Server validates the token against GitLab's /oauth/token/info and stores it per session

The server enforces at least the api scope during authorization, even if the MCP client requests fewer scopes (e.g. Claude.ai sends ai_workflows which is insufficient).

All existing auth modes (REMOTE_AUTHORIZATION, GITLAB_USE_OAUTH, PAT, cookie) are completely unchanged.

Configuration

docker run -d \
  -e STREAMABLE_HTTP=true \
  -e GITLAB_MCP_OAUTH=true \
  -e GITLAB_OAUTH_APP_ID="your-gitlab-oauth-app-client-id" \
  -e GITLAB_API_URL="https://gitlab.example.com/api/v4" \
  -e MCP_SERVER_URL="https://your-mcp-server.example.com" \
  -p 3002:3002 \
  zereight050/gitlab-mcp

Claude.ai config — no headers needed:

{
  "mcpServers": {
    "GitLab": {
      "url": "https://your-mcp-server.example.com/mcp"
    }
  }
}

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	GitLab instance API URL
STREAMABLE_HTTP	Yes	Must be true (SSE not supported)
MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL	No	true for local HTTP dev only

[PedroFCM]

Hi @titouanmathis! Great work on this branch, I see it bringing great value for me as well.

I've been testing it with my Gitlab instance, by deploying the MCP on AWS (behind AWS ALB on ECS Fargate) and it's working well! A couple of suggestions from my deployment tests:

1. OAuth scopes should respect GITLAB_READ_ONLY_MODE

REQUIRED_GITLAB_SCOPES is hardcoded to ["api"]. When GITLAB_READ_ONLY_MODE=true, it should default to ["read_api"] to follow least-privilege. I implemented this by passing a readOnly flag through createGitLabOAuthProvider():

// oauth-proxy.ts — constructor
this._requiredScopes = readOnly ? ["read_api"] : ["api"];

// index.ts — call site
const oauthProvider = createGitLabOAuthProvider(
  gitlabBaseUrl, GITLAB_OAUTH_APP_ID!, "GitLab MCP Server", GITLAB_READ_ONLY_MODE
);

2. Add trust proxy for reverse proxy deployments

When running behind a load balancer (ALB, nginx, etc.), express-rate-limit sees all requests from the proxy's IP and rate-limits everyone together.
Adding before app.use(express.json()) fixes this - Express reads X-Forwarded-For for the real client IP

// Configure Express middleware
app.set("trust proxy", 1) // new instruction
app.use(express.json())

Happy to open a PR against your branch with either or both changes if you're interested.

[titouanmathis]

Hey @PedroFCM, thanks for the feedback, I pushed 2 commits that should address both of your suggestions. Let me know if it works well for you!

[PedroFCM]

It works as expected, thanks!