Skip to content
GitLab MCP Server GitLab MCP Server GitLab MCP Server

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

Section titled “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

Section titled “Log levels”

Stderr levels (LOG_LEVEL)

Section titled “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)

Section titled “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

Section titled “Configuration”

Set the log level via environment variable:

Terminal window
# 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

Section titled “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": 33,
      "resources": 46,
      "prompts": 37
    }
  }
}

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

Security rules

Section titled “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