Skip to content

environment-variables.md

Latest commit

 

History

History
622 lines (396 loc) · 19.3 KB

environment-variables.md

File metadata and controls

622 lines (396 loc) · 19.3 KB
Raw

Environment Variables Reference

This document is the reference source of truth for runtime environment variables used by @zereight/mcp-gitlab.

Use an API URL, not the GitLab web root:

  • https://gitlab.com/api/v4
  • https://your-gitlab.example.com/api/v4

Authentication

GITLAB_PERSONAL_ACCESS_TOKEN

Default static GitLab Personal Access Token used in standard mode.

GITLAB_JOB_TOKEN

Optional GitLab CI job token.

GITLAB_AUTH_COOKIE_PATH

Optional Netscape cookie file path for cookie-based authentication.

GITLAB_USE_OAUTH

Set to true to enable local browser-based OAuth2 authentication.

GITLAB_OAUTH_CLIENT_ID

Client ID for local OAuth2 authentication.

GITLAB_OAUTH_CLIENT_SECRET

Client secret for confidential OAuth applications only.

GITLAB_OAUTH_REDIRECT_URI

OAuth callback URI for the local browser flow.

Use this only with local OAuth (GITLAB_USE_OAUTH=true). The local OAuth flow starts a browser on the same machine as the MCP server and listens for the callback on a local HTTP server.

Change this when the default port conflicts with another process, or when your GitLab OAuth Application is registered with a different local callback URL such as http://127.0.0.1:9999/callback.

This variable is not used to choose the remote MCP OAuth callback URL. It does not change the redirect_uri sent by remote MCP clients and is not a fix for Unregistered redirect_uri errors when GITLAB_MCP_OAUTH=true.

Default:

  • http://127.0.0.1:8888/callback

GITLAB_OAUTH_TOKEN_PATH

Optional custom path for the stored OAuth token file.

GITLAB_OAUTH_TOKEN_SCRIPT

Optional command that prints an OAuth access token to stdout. When set with GITLAB_USE_OAUTH=true, the server uses this command instead of the local browser OAuth flow and token file refresh.

Example:

GITLAB_USE_OAUTH=true \
GITLAB_OAUTH_TOKEN_SCRIPT="coder external-auth access-token gitlab"

The command may also print JSON with an access_token or token field.

GITLAB_OAUTH_TOKEN_SCRIPT_TIMEOUT_SECONDS

Timeout for GITLAB_OAUTH_TOKEN_SCRIPT. Default: 30.

Remote / Multi-User Authentication

REMOTE_AUTHORIZATION

Set to true to require GitLab auth headers per HTTP session.

See also: Custom Agents and Multiple PAT Setup.

Notes:

  • Requires STREAMABLE_HTTP=true
  • Not compatible with SSE=true
  • Supports header-based auth such as:
    • Authorization: Bearer <token>
    • Private-Token: <token>
    • Job-Token: <token>

GITLAB_ALLOW_UNAUTHENTICATED_TOOL_DISCOVERY

Optional. Set to true to let unauthenticated clients call tools/list in REMOTE_AUTHORIZATION=true deployments. This is intended for MCP gateways or admin UIs that need to inspect tool metadata before a user provides a GitLab token.

Default:

  • false

Security notes:

  • Only initialize, notifications/initialized, and tools/list may proceed without auth.
  • tools/call and all GitLab API access still require request auth headers.
  • Tool names and schemas can reveal enabled server capabilities; enable this only when that metadata is safe to expose.

SESSION_TIMEOUT_SECONDS

Per-session auth timeout in seconds when using remote authorization.

Default:

  • 3600

GITLAB_MCP_OAUTH

Enables the server-side MCP OAuth proxy mode for remote MCP clients.

GITLAB_OAUTH_CALLBACK_PROXY

Set to true to make the MCP server handle GitLab's OAuth callback at {MCP_SERVER_URL}/callback, then redirect the client with a proxy authorization code. This keeps the GitLab OAuth Application redirect URI fixed to one MCP server callback URL instead of requiring each MCP client's callback URL to be registered in GitLab.

Use this with remote MCP OAuth (GITLAB_MCP_OAUTH=true) when clients such as OpenCode, MCPJam, Claude.ai, or another MCP client send their own callback URL. It is recommended when you cannot register every client callback URI in GitLab Admin.

This has a different purpose from GITLAB_OAUTH_REDIRECT_URI: callback proxy mode turns a client-owned callback into the MCP server callback registered in GitLab. Register {MCP_SERVER_URL}/callback in GitLab Admin.

MCP_SERVER_URL

Public HTTPS MCP server base URL required for MCP OAuth mode.

GITLAB_OAUTH_APP_ID

Pre-registered GitLab OAuth application ID used by MCP OAuth mode.

GITLAB_OAUTH_SCOPES

Comma-separated scopes for MCP OAuth mode.

Examples:

  • api
  • api,read_user

GITLAB_OAUTH_ALLOWED_GROUPS

Comma-separated list of GitLab group full paths. When set, only users who belong to at least one of these groups (or any of their subgroups) are allowed to use the server. Users who authenticate successfully via OAuth but are not members of any matching group receive a 401 Access Denied response.

Requires GITLAB_MCP_OAUTH=true.

Deprecation notice: The old name GITLAB_ALLOWED_GROUPS is still accepted but will be removed in a future major version. Migrate to GITLAB_OAUTH_ALLOWED_GROUPS.

Examples:

  • my-org — allows all members of my-org and any subgroup such as my-org/engineering or my-org/engineering/backend
  • my-org/engineering,my-org/security — allows members of either group or their subgroups

Notes:

  • Group paths are globally unique on a GitLab instance — path squatting is not possible.
  • Matching is case-insensitive and checks the group's full_path (e.g. my-org/team-a), not its display name.
  • The check is performed once at token issuance (when the MCP client exchanges the authorization code for tokens), not on every subsequent request. Existing sessions are not retroactively revoked when this value changes; users are re-checked when they complete a new OAuth flow or refresh through token issuance.
  • The groups lookup uses the user's OAuth token. If GitLab rejects that lookup (for example because the token lacks a usable scope), login fails closed with access denied.
  • No additional service account credentials are needed.
  • Leave unset to allow any authenticated GitLab user (default behaviour).

ENABLE_DYNAMIC_API_URL

Set to true to allow the GitLab API URL to be supplied per request.

Notes:

  • Requires REMOTE_AUTHORIZATION=true
  • Uses the X-GitLab-API-URL request header in HTTP mode
  • The header URL must use an allowed host: any host in GITLAB_API_URL, plus any host in GITLAB_ALLOWED_HOSTS

GITLAB_ALLOWED_HOSTS

Comma-separated additional hosts or GitLab base/API URLs allowed for X-GitLab-API-URL when ENABLE_DYNAMIC_API_URL=true. This is only for hosts beyond those already listed in GITLAB_API_URL; do not repeat GITLAB_API_URL hosts here. Examples: gitlab.example.com,https://gitlab.company.com:8443/api/v4.

MCP_TRUST_PROXY

Set to true when the MCP server runs behind a trusted reverse proxy.

Effects when enabled:

  • Public download URLs (Streamable HTTP): derives the client-facing origin from Forwarded / X-Forwarded-* when MCP_SERVER_URL is unset.
  • Express trust proxy: enables proxy-aware req.ip in both Streamable HTTP and SSE transports.
  • OAuth rate limiting (GITLAB_MCP_OAUTH=true): normalizes X-Forwarded-For values that include a source port (for example 1.2.3.4:5678 or [2001:db8::1]:5678) before express-rate-limit keys requests on /authorize, /token, /register, and /revoke.
  • /mcp rate limiting (Streamable HTTP): keys POST and DELETE /mcp requests by the real client IP instead of the reverse-proxy IP. Required for shared deployments behind a single egress IP so each user gets their own MAX_REQUESTS_PER_MINUTE bucket.

Use this only when the proxy is trusted and direct client access to the MCP server port is blocked. When unset, forwarded headers are ignored for URL derivation and Express does not trust X-Forwarded-For.

Migration note: OAuth deployments that previously relied on implicit proxy trust must set MCP_TRUST_PROXY=true explicitly.

Recognized forwarded headers for URL derivation:

  • Forwarded
  • X-Forwarded-Proto
  • X-Forwarded-Host
  • X-Forwarded-Prefix

Stateless mode (multi-pod HPA)

See Stateless Mode for the full design and trade-off discussion. Stateless mode makes the OAuth proxy, DCR registry, and Mcp-Session-Id path safe to distribute across multiple pods with no shared cache, no sticky sessions, and no external dependency.

OAUTH_STATELESS_MODE

Set to true to enable stateless encodings for client_id, OAuth state, OAuth code, and Mcp-Session-Id. Default false — legacy (per-pod memory) behaviour is unchanged.

OAUTH_STATELESS_SECRET

Required when OAUTH_STATELESS_MODE=true. Base64url-encoded ≥32 bytes. Must be identical across all pods.

Generate with:

openssl rand -base64 32

OAUTH_STATELESS_SECRET_PREVIOUS

Optional. Accepted on reads only; during key rotation the previous secret keeps verifying tokens minted before the swap. Remove after max(TTL) has elapsed.

OAUTH_STATELESS_CLIENT_TTL_SECONDS

Max age for a signed DCR client_id. Default 86400 (24 h).

OAUTH_STATELESS_PENDING_TTL_SECONDS

Max age for a sealed OAuth state during the callback-proxy /authorize → /callback hop. Default 600 (10 min).

OAUTH_STATELESS_STORED_TTL_SECONDS

Max age for a sealed proxy authorization code during the /callback → /token hop. Default 600 (10 min).

OAUTH_STATELESS_SESSION_TTL_SECONDS

Inactivity timeout for a sealed Mcp-Session-Id, evaluated against the iat of the most recently minted sid. The server mints a fresh sid on every /mcp request, so continuously-used sessions never expire; a session is only rejected when no traffic has arrived for longer than this window. Defaults to SESSION_TIMEOUT_SECONDS when unset, matching the legacy stateful setAuthTimeout semantics without additional configuration.

Value validation: must parse as a finite positive integer. If the env var (or --oauth-stateless-session-ttl CLI flag) is unset or invalid, the value falls back to SESSION_TIMEOUT_SECONDS when that is itself a finite positive integer, otherwise to the hardcoded default of 3600 seconds. Misconfigurations never produce NaN — this guarantees the TTL check in the stateless codec (ttlSec > 0 in checkIat) always enforces an inactivity window for sealed sids.

Core GitLab Configuration

GITLAB_API_URL

GitLab API base URL.

Default:

  • https://gitlab.com/api/v4

GITLAB_PROJECT_ID

Optional default project ID.

GITLAB_ALLOWED_PROJECT_IDS

Optional comma-separated allowlist of project IDs.

Behavior:

  • One project ID: acts like a default locked project
  • Multiple project IDs: restricts access to those projects only

GITLAB_READ_ONLY_MODE

Set to true to expose only read-only tools.

Deprecation notice: GITLAB_READ_ONLY_MODE and --read-only=true are kept for backward compatibility but will be removed in a future major version. Use GITLAB_PERMISSION_MODE=readonly or --permission-mode=readonly instead.

When set to true it takes precedence over GITLAB_PERMISSION_MODE.

GITLAB_PERMISSION_MODE

Permission level for the exposed tool surface. One of:

Value Read Create/Update Delete
readonly ✅ ❌ ❌
modify ✅ ✅ ❌
full ✅ ✅ ✅

Default: full

CLI: --permission-mode

Behavior:

  • readonly is equivalent to GITLAB_READ_ONLY_MODE=true
  • modify hides all delete_* tools from tools/list, rejects them when called directly, and rejects delete/destroy/remove mutations sent through execute_graphql
  • Invalid values fail startup with an error
  • GITLAB_DENIED_TOOLS_REGEX and the tool policy variables still apply on top

GITLAB_DISABLE_VERSION_CHECK

Set to true to disable the startup update check.

By default the server queries the npm registry once at startup (3 second timeout, fail-silent — it never blocks or breaks startup) and logs a notice to stderr when a newer version than the one running is available. No data other than the standard HTTP request to registry.npmjs.org is sent.

Set this in offline or air-gapped environments, or when you do not want the server to make any outbound request beyond your GitLab instance.

Tool Exposure and Filtering

GITLAB_TOOLSETS

Comma-separated list of toolset IDs to enable.

For agent-specific tool surfaces, see Custom Agents and Multiple PAT Setup.

Special value:

  • all

GITLAB_TOOLS

Comma-separated list of individual tool names to add on top of enabled toolsets.

For restricted custom agents, combine this with GITLAB_TOOLSETS, GITLAB_DENIED_TOOLS_REGEX, and the tool policy variables documented in Custom Agents and Multiple PAT Setup.

GITLAB_DENIED_TOOLS_REGEX

Optional regex denylist for tool names.

GITLAB_TOOL_POLICY_APPROVE

Comma-separated tool names that require explicit confirmation before execution. Tools listed here are visible in tools/list with confirmationHint: true but will return a confirmation prompt unless called with _confirmed: true.

CLI: --tool-policy-approve

Examples:

  • create_issue,delete_issue
  • merge_merge_request

GITLAB_TOOL_POLICY_HIDDEN

Comma-separated tool names to hide from tools/list. Hidden tools are not visible to the agent but remain callable if invoked directly. Takes precedence over GITLAB_TOOL_POLICY_APPROVE when the same tool appears in both.

CLI: --tool-policy-hidden

Examples:

  • delete_issue,delete_wiki_page

USE_GITLAB_WIKI

Legacy additive flag for wiki-related tools. Prefer GITLAB_TOOLSETS=wiki.

USE_MILESTONE

Legacy additive flag for milestone-related tools. Prefer GITLAB_TOOLSETS=milestones.

USE_PIPELINE

Legacy additive flag for pipeline-related tools. Prefer GITLAB_TOOLSETS=pipelines.

Deprecation notice: The USE_* flags are kept for backward compatibility only and cover just three toolsets. Use GITLAB_TOOLSETS (groups) and GITLAB_TOOLS (individual tools) instead.

Transport and Server Runtime

STREAMABLE_HTTP

Set to true to run the Streamable HTTP transport.

When using server-side GitLab credentials (GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_JOB_TOKEN, GITLAB_AUTH_COOKIE_PATH, or GITLAB_USE_OAUTH), also set one MCP-layer auth mode: REMOTE_AUTHORIZATION=true, GITLAB_MCP_OAUTH=true, or STREAMABLE_HTTP_AUTH_TOKEN.

Streamable HTTP allows /mcp requests when the Host header is a loopback host on any port (127.0.0.1, localhost, [::1]), matches MCP_SERVER_URL, matches the HOST:PORT the server binds to, or is listed in MCP_ALLOWED_HOSTS. When an Origin header is present, it must be a loopback origin, match MCP_SERVER_URL, match the bound http://HOST:PORT origin, or be listed in MCP_ALLOWED_ORIGINS.

Upgrade note: deployments reached through a non-loopback hostname or IP (for example an internal DNS name or LAN IP) must set MCP_SERVER_URL or MCP_ALLOWED_HOSTS, otherwise /mcp requests are rejected with 403.

STREAMABLE_HTTP_AUTH_TOKEN

Bearer token required on /mcp when Streamable HTTP uses server-side GitLab credentials without REMOTE_AUTHORIZATION or GITLAB_MCP_OAUTH.

MCP_ALLOWED_HOSTS

Comma-separated extra allowed Host header values for /mcp. Use this when the public host clients send differs from MCP_SERVER_URL. Values may be bare hosts (mcp.example.com) or host:port pairs.

MCP_ALLOWED_ORIGINS

Comma-separated extra allowed browser origins for /mcp, for example https://mcp.example.com.

SSE

Set to true to run the legacy SSE transport.

Notes:

  • Not compatible with REMOTE_AUTHORIZATION=true
  • Startup requires SSE_AUTH_TOKEN unless you explicitly set SSE_DANGEROUSLY_ALLOW_UNAUTHENTICATED_REMOTE=true

SSE_AUTH_TOKEN

Bearer token required for /sse and /messages. Use this for any SSE deployment.

When SSE runs behind a reverse proxy on a different public hostname, also set MCP_SERVER_URL to the external URL or enable MCP_TRUST_PROXY=true so forwarded Host / Origin headers from the proxy are accepted.

SSE_DANGEROUSLY_ALLOW_UNAUTHENTICATED_REMOTE

Set to true only if you intentionally expose SSE without MCP-layer auth. This allows any network client to use the server's configured GitLab token.

HOST

Bind host for HTTP transports.

Default:

  • 127.0.0.1

PORT

HTTP server port.

Default:

  • 3002

MCP_SERVER_NAME

Name this server advertises to MCP clients during the initialize handshake (serverInfo.name). Set a distinct value to tell multiple GitLab MCP deployments apart in client UIs and logs.

Default:

  • zereight-gitlab-mcp-server

MAX_REQUESTS_PER_MINUTE

Maximum requests allowed per rolling 60-second window. Applies to Streamable HTTP and SSE remote deployments. Valid range: 1–1000.

Default:

  • 60

This single value is reused in three places (whichever limit is hit first wins):

Layer Key Routes
Express middleware Client IP POST / DELETE /mcp
Session handler MCP session ID Existing sessions when REMOTE_AUTHORIZATION=true or GITLAB_MCP_OAUTH=true
Download proxy Auth token GET /downloads/*

When MCP_TRUST_PROXY is unset behind a reverse proxy, all clients share one IP bucket and the per-IP limit becomes the bottleneck for the whole deployment.

Shared deployment starting point: MCP_TRUST_PROXY=true with MAX_REQUESTS_PER_MINUTE=300 (raise if /metrics shows rejectedByRateLimit growth). This limits MCP server abuse; GitLab API rate limits are separate upstream constraints.

Monitor rejections via /metrics → rejectedByRateLimit or gitlab_mcp_requests_rejected_total{reason="rate_limit"}.

MAX_SESSIONS

Maximum concurrent MCP sessions on a single server instance (Streamable HTTP / remote authorization / MCP OAuth).

Default:

  • 1000

When the limit is reached, new session creation is rejected until an existing session expires or is closed.

Network and TLS

HTTP_PROXY

Optional outbound HTTP proxy.

HTTPS_PROXY

Optional outbound HTTPS proxy.

NO_PROXY

Optional proxy bypass rules.

NODE_TLS_REJECT_UNAUTHORIZED

Controls TLS certificate verification.

GITLAB_CA_CERT_PATH

Optional custom CA certificate path.

GITLAB_POOL_MAX_SIZE

Maximum GitLab client pool size.

Recommended Starting Sets

Simple local PAT setup

  • GITLAB_PERSONAL_ACCESS_TOKEN
  • GITLAB_API_URL

Local OAuth setup

  • GITLAB_USE_OAUTH=true
  • GITLAB_OAUTH_CLIENT_ID
  • GITLAB_OAUTH_REDIRECT_URI
  • GITLAB_API_URL

Remote shared deployment

  • STREAMABLE_HTTP=true
  • REMOTE_AUTHORIZATION=true or GITLAB_MCP_OAUTH=true
  • MCP_TRUST_PROXY=true (when behind a reverse proxy)
  • MAX_REQUESTS_PER_MINUTE=300 (tune from metrics)
  • MCP_SERVER_URL or MCP_ALLOWED_HOSTS (non-loopback public host)
  • HOST
  • PORT

Related Guides