Configuration

Developer Documentation

For the complete technical reference, see docs/configuration.md in the repository.

GitLab MCP Server needs almost nothing to start. In stdio mode — the default used by IDE integrations — you set just two things: which GitLab instance to talk to (GITLAB_URL) and a personal access token to talk with (GITLAB_TOKEN). On GitLab.com even the URL is optional, because GITLAB_URL defaults to https://gitlab.com, so a single GITLAB_TOKEN is enough; point GITLAB_URL at your own host for self-managed instances. In HTTP mode the server holds no credentials at all — each client sends its own token (and optionally its own GitLab URL) with every request. Everything else on this page is optional and ships with a safe default.

Stdio mode reads its configuration from environment variables or a .env file; HTTP mode reads CLI flags. This page covers the options most users need; see the repository environment reference and CLI reference for the exhaustive tables.

Quick orientation

Stdio mode (default) — configure via environment variables or a .env file. This is the mode used by IDE integrations (VS Code, Cursor, Claude Desktop, etc.).

HTTP mode (--http) — configure via CLI flags. Used for shared/remote deployments (Docker, Fly.io, Kubernetes). Jump to HTTP mode flags.

Required variables

GitLab MCP Server requires exactly one variable to start in stdio mode — the rest are optional and default to safe values:

Variable	Description	Example
GITLAB_TOKEN	Personal Access Token with api scope	glpat-xxxxxxxxxxxxxxxxxxxx

Core options

Variable	Default	Description
GITLAB_URL	https://gitlab.com	GitLab instance base URL. Set this for self-managed instances
GITLAB_SKIP_TLS_VERIFY	false	Skip TLS certificate verification for self-signed certs
TOOL_SURFACE	dynamic	Canonical tool catalog selector: dynamic, meta, or individual
META_TOOLS	legacy	Deprecated compatibility selector. true maps to meta, false maps to individual, and dynamic values map to the matching TOOL_SURFACE value when TOOL_SURFACE is absent
CAPABILITY_SURFACE	full	Resource and prompt catalog selector: full keeps the complete catalog; minimal keeps the gitlab://tools manifest, and disables optional resources, prompts, and workflow guides
META_PARAM_SCHEMA	opaque	Meta-tool input-schema strategy: opaque (default), compact (6.5x opaque size), or full (11.9x opaque size). Applies to meta-tool tools/list schemas only
GITLAB_TIER	(auto-detect)	GitLab edition selector: free/ce, premium, or ultimate. When set, used verbatim; when unset, detected from GET /license (fallback free). Tier gates Enterprise/Premium tools and prunes per-field schema entries via pruneSchemaFieldsByTier (see internal/tools/action_catalog.go)
GITLAB_READ_ONLY	false	Disable all mutating tools (create, update, delete)
GITLAB_SAFE_MODE	false	Return structured JSON preview instead of executing mutating tools (dry-run mode)
EMBEDDED_RESOURCES	true	Embed canonical gitlab:// MCP resource URIs in get-tool results; set false for clients that do not tolerate duplicate content blocks
EXCLUDE_TOOLS	—	Comma-separated list of tool names to exclude (e.g., gitlab_delete_project,gitlab_admin)
GITLAB_IGNORE_SCOPES	false	Skip automatic PAT scope detection — register all tools regardless of token scopes
LOG_LEVEL	info	Log verbosity: debug, info, warn, error
EVAL_SURFACE_ENTERPRISE	false	cmd/eval_mcp_surfaces: run the enterprise case set on top of the base corpus
EVAL_SURFACE_CASE_SET	ce	cmd/eval_mcp_surfaces: case-set selector — ce (CE only) or all (CE+Enterprise)
EVAL_SURFACE_FIXTURE_SMOKE	false	cmd/eval_mcp_surfaces: limit the run to fixture-smoke cases (fast smoke check)

Tip

Dynamic mode (TOOL_SURFACE=dynamic) is the default and lowest-token catalog. It exposes gitlab_find_action and gitlab_execute_action, while the same GitLab actions remain available through the canonical action catalog.

Use TOOL_SURFACE=meta when a client or workflow prefers consolidated domain dispatchers with an action parameter.

See Dynamic toolset for the find/execute workflow.

For deployments using the dynamic tool surface where resources and prompts dominate initial context, set CAPABILITY_SURFACE=minimal. It keeps gitlab://tools for action discovery, and omits optional resources, prompts, and workflow guides. This does not remove action schemas from dynamic discovery: use gitlab_find_action to retrieve exact schemas inline before calling gitlab_execute_action, or read gitlab://tools/{id} for a manifest entry. The default remains full; no schemas-only capability mode is exposed today.

Auto-update

Variable	Default	Description
AUTO_UPDATE	true	Auto-update behavior: true (apply on start), check (notify only), false (disabled)
AUTO_UPDATE_REPO	jmrplens/gitlab-mcp-server	GitHub repository for release assets
AUTO_UPDATE_INTERVAL	1h	Periodic check interval (HTTP mode only)
AUTO_UPDATE_TIMEOUT	60s	Startup/background update timeout (range: 5s–10m)

Admin options

Variable	Default	Description
YOLO_MODE	false	Skip destructive action confirmations (not recommended)
AUTOPILOT	false	Same as YOLO_MODE — skip destructive confirmations
GITLAB_MCP_ALLOWED_IMPORT_DIRS	—	Additional OS path-list-separated directories allowed for local project/group import archives
RATE_LIMIT_RPS	0	Per-server tools/call rate limit in req/s (0 = disabled)
RATE_LIMIT_BURST	40	Token-bucket burst size when RATE_LIMIT_RPS > 0

Example .env file

.env

# Required
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

# Optional
GITLAB_SKIP_TLS_VERIFY=false
TOOL_SURFACE=dynamic
GITLAB_TIER=free
GITLAB_READ_ONLY=false
GITLAB_SAFE_MODE=false
EXCLUDE_TOOLS=
GITLAB_IGNORE_SCOPES=false
LOG_LEVEL=info

# Auto-update
AUTO_UPDATE=true

For self-managed GitLab, add GITLAB_URL=https://gitlab.example.com.

Client configuration

VS Code / Copilot

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Secure token configuration using VS Code input variables:

{
  "inputs": [
    {
      "id": "gitlab-token",
      "type": "promptString",
      "description": "GitLab Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "${input:gitlab-token}"
      }
    }
  }
}

Tip

The password: true option masks the token input. VS Code will prompt for it once per session.

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Code

claude mcp add gitlab \
  --transport stdio \
  -- /path/to/gitlab-mcp-server

Set environment variables before launching:

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

Set GITLAB_URL here only for self-managed instances.

Or use a .env file in the working directory.

Continue

Add to ~/.continue/config.yaml (or your workspace .continue/config.yaml):

mcpServers:
  - name: gitlab
    command: /path/to/gitlab-mcp-server
    env:
      GITLAB_TOKEN: glpat-xxxxxxxxxxxxxxxxxxxx

Reload the Continue window after editing the config. See the Continue MCP docs for HTTP-mode and OAuth alternatives.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (Cascade → Plugins → Configure):

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Windsurf or click Refresh in the Plugins panel to pick up changes.

JetBrains AI

JetBrains IDEs (IntelliJ IDEA, GoLand, PyCharm, etc.) with the AI Assistant plugin support MCP servers via Settings → Tools → AI Assistant → Model Context Protocol.

Add a stdio entry pointing at the binary:

• Name: gitlab
• Command: /path/to/gitlab-mcp-server
• Environment variables: GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Add GITLAB_URL=https://gitlab.example.com for self-managed GitLab.

Alternatively, create .idea/mcp.json in the project root with the same JSON shape used by VS Code / Cursor. Restart the IDE after editing.

HTTP mode flags

When running in HTTP mode (--http), configuration uses CLI flags instead of environment variables:

Flag	Default	Description
--http	false	Enable HTTP transport mode
--http-addr	:8080	Listen address and port
--gitlab-url	—	Fixed GitLab instance URL. Omit to require GITLAB-URL per request
--skip-tls-verify	false	Skip TLS verification
--tool-surface	dynamic	Canonical tool catalog selector: dynamic, meta, or individual
--meta-tools	(unset)	Deprecated compatibility flag. Use --tool-surface=individual instead of --meta-tools=false
--meta-param-schema	opaque	Meta-tool params schema mode: opaque, compact, or full; applies to meta-tool schemas only
--capability-surface	full	Resource and prompt catalog selector: full or minimal; minimal keeps the gitlab://tools manifest, and omits optional resources, workflow guides, and prompts
--tier	(auto-detect)	Force GitLab edition: free/ce, premium, or ultimate; omit to auto-detect CE/EE per token+URL entry. Replaces the deprecated --enterprise flag
--read-only	false	Read-only mode
--safe-mode	false	Intercept mutating tools and return a JSON preview instead of executing them
--embedded-resources	true	Embed canonical MCP resource URIs in get-tool results
--exclude-tools	—	Comma-separated tool names to exclude
--ignore-scopes	false	Skip PAT scope detection
--max-http-clients	100	Maximum concurrent client sessions
--session-timeout	30m	Idle session timeout
--http-idle-timeout	0 (disabled)	HTTP server idle connection timeout. Default 0 disables idle closure, so --session-timeout is the effective lifetime; set a positive duration to recycle idle connections sooner
--auto-update	true	Auto-update mode
--auto-update-repo	jmrplens/gitlab-mcp-server	GitHub release repository
--auto-update-interval	1h	Periodic update check interval
--auto-update-timeout	60s	Startup/background update timeout (5s–10m)
--auth-mode	legacy	Authentication mode: legacy or oauth
--oauth-cache-ttl	15m	OAuth token identity cache TTL (1m–2h)
--revalidate-interval	15m	Token re-validation interval; 0 to disable (upper bound: 24h)
--rate-limit-rps	0	Per-server tools/call rate limit in req/s (0 = disabled)
--rate-limit-burst	40	Token-bucket burst size when --rate-limit-rps > 0
--trusted-proxy-header	—	HTTP header with real client IP for rate limiting behind proxies (e.g. Fly-Client-IP, X-Forwarded-For)

Surface evaluator flags (used by cmd/eval_mcp_surfaces only):

Flag	Default	Description
--max-output-retries	2	Re-run a task when it fails solely due to malformed model tool-call output
--case-set	ce	Case-set selector: ce (CE only) or all (CE+Enterprise)
--enterprise-case-set	false	Run the enterprise case set on top of the base corpus
--fixture-smoke	false	Limit the run to fixture-smoke cases (fast smoke check)

General flags (both stdio and HTTP modes):

Flag	Default	Description
--shutdown	false	Terminate all running instances and exit

Example:

# Single GitLab.com instance (fixed URL for all clients; replace for self-managed GitLab)
./gitlab-mcp-server \
  --http \
  --http-addr=0.0.0.0:8080 \
  --gitlab-url=https://gitlab.com \
  --max-http-clients=200 \
  --session-timeout=1h

# Multi-instance (each client specifies their GitLab URL via GITLAB-URL header)
./gitlab-mcp-server \
  --http \
  --http-addr=0.0.0.0:8080

Configuration load order

The server loads configuration in the following order (later sources override earlier ones):

1. ~/.gitlab-mcp-server.env — User-level defaults (home directory)
2. .env — Project-level configuration (current working directory)
3. System environment variables — Exported variables in the shell
4. CLI flags — Command-line arguments (highest priority)

Note

In HTTP mode, GITLAB_TOKEN is not loaded from environment variables. Each client provides their own token via the HTTP request. Clients can send a GITLAB-URL header only when the server starts without --gitlab-url.

When --gitlab-url is configured, it is authoritative and client-provided GITLAB-URL values are ignored and logged. Other server policy options, including schema size (--meta-param-schema) and rate limits (--rate-limit-rps, --rate-limit-burst), cannot be overridden per request.

Self-signed certificates

For GitLab instances with self-signed TLS certificates:

GITLAB_SKIP_TLS_VERIFY=true

Caution

Only use this in trusted network environments. It disables certificate verification for all connections to the GitLab instance.

Read-only mode

Enable GITLAB_READ_ONLY=true to restrict the server to read-only operations. All tools that create, update, or delete resources are disabled. This is useful for:

• Audit and compliance environments
• Shared servers where users should only query data
• Tokens with read_api scope

Safe mode

Enable GITLAB_SAFE_MODE=true to intercept mutating tools and return a structured JSON preview of what would be executed, without actually performing the operation. Read-only tools work normally. This is useful for:

• Reviewing operations before execution (dry-run)
• Training environments where you want to see tool behavior
• Debugging tool parameters without side effects

Note

If GITLAB_READ_ONLY=true is also set, it takes precedence — mutating tools are fully disabled rather than previewed.

Frequently asked questions

What is the minimum configuration?

In stdio mode, a single GITLAB_TOKEN with the api scope is enough to start — every other variable is optional and defaults to a safe value. GITLAB_URL defaults to https://gitlab.com, so you set it only when connecting to a self-managed instance. For a read-only setup, use a read_api token and add GITLAB_READ_ONLY=true. In HTTP mode, no token is configured on the server at all; each client sends its own token with every request.

stdio vs HTTP — which mode do I use?

Use stdio mode (the default) for local, single-user setups such as IDE integrations like VS Code, Cursor, and Claude Desktop; it is configured through environment variables or a .env file. Use HTTP mode (--http) for shared or remote deployments such as Docker, Fly.io, or Kubernetes, where configuration uses CLI flags and each client authenticates with its own GitLab token per request.

How do I point at a self-managed GitLab instance?

Set GITLAB_URL to your instance base URL, for example GITLAB_URL=https://gitlab.example.com (in HTTP mode, use the --gitlab-url flag instead). If the instance uses a self-signed or internal CA certificate, also set GITLAB_SKIP_TLS_VERIFY=true (or --skip-tls-verify in HTTP mode), but only on a trusted network — it disables certificate verification for all connections to GitLab.

How do I pick a tool surface (dynamic, meta, or individual)?

Set the TOOL_SURFACE variable (or the --tool-surface flag in HTTP mode). dynamic is the default and lowest-token catalog: it exposes gitlab_find_action and gitlab_execute_action while keeping every GitLab action reachable through the canonical action catalog. Choose meta when a client prefers consolidated domain dispatchers with an action parameter, and individual to register one MCP tool per GitLab operation.