Logging

GitLab MCP Server uses dual logging — log messages are sent both to stderr (for terminal/file capture) and to the MCP client via the protocol’s logging capability.

Dual output

flowchart LR
    A[Tool Call] --> B[Logger]
    B --> C[stderr<br/>Human-readable / JSON]
    B --> D[MCP notifications/message<br/>Client UI]

    style A fill:#6366f1,color:#fff
    style B fill:#8b5cf6,color:#fff
    style C fill:#3b82f6,color:#fff
    style D fill:#22c55e,color:#fff

Destination	Format	Purpose
stderr	Human-readable text or JSON	Terminal output, file redirection, debugging
MCP protocol	`notifications/message`	Displayed in the MCP client’s UI (e.g., VS Code Output panel)

This ensures logs are always visible regardless of the client’s logging support.

Log levels

Stderr levels (`LOG_LEVEL`)

The LOG_LEVEL environment variable accepts four values:

Level	When Used
debug	Detailed diagnostic information — tool call parameters, API request/response details, session pool operations
info	Normal operational events — server startup, tool registration, update checks
warn	Non-fatal issues — network timeouts, missing optional configuration, deprecated usage
error	Failures — authentication errors, API failures, unrecoverable tool errors

MCP protocol levels (RFC 5424)

The MCP notifications/message supports all eight RFC 5424 severity levels. Clients can filter via logging/setLevel:

Level	Severity	When Used
debug	Lowest	Diagnostic details (tool parameters, API traces)
info		Normal events (startup, registration)
notice		Significant but normal conditions
warning		Potential issues (timeouts, deprecation)
error		Operation failures (API errors, auth failures)
critical		Critical conditions requiring immediate attention
alert		Action must be taken immediately
emergency	Highest	System is unusable

Configuration

Set the log level via environment variable:

# Stdio mode
LOG_LEVEL=debug ./gitlab-mcp-server

# HTTP mode
LOG_LEVEL=info ./gitlab-mcp-server --http --gitlab-url=https://gitlab.com

The default level is info.

MCP log messages

When the MCP client supports logging, the server sends structured log notifications:

{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "info",
    "logger": "gitlab-mcp-server",
    "data": {
      "message": "starting MCP server",
      "transport": "stdio",
      "version": "x.y.z",
      "tools": 32,
      "resources": 46,
      "prompts": 38
    }
  }
}

The counts in this example represent the active runtime configuration and can vary by tool surface, capability surface, and Enterprise/Premium gating.

Security rules

Log messages follow strict security rules:

No tokens — GitLab tokens are never included in log messages
Masked identifiers — In HTTP mode, tokens are shown as ...a1b2 (last 4 characters only)
No PII — User-submitted data is not logged at info level or above
Debug only — Detailed request/response data is only logged at debug level