Auto-update

GitLab MCP Server can automatically detect, download, and apply new releases from GitHub. Updates use a rename trick — the running binary is renamed to .old, the new binary is placed at the original path, and on Unix the process re-executes seamlessly.

Update modes

The AUTO_UPDATE variable controls how updates are handled:

Value	Mode	Behavior
`true` (default)	Auto-apply	Detect and apply updates automatically
`check`	Notify only	Detect updates and log availability, but do not apply
`false`	Disabled	Skip all update checks entirely

Accepted aliases: 1/yes for true, 0/no for false. The value is case-insensitive.

How it works

sequenceDiagram
    participant Server as gitlab-mcp-server
    participant GitHub as GitHub Releases API
    participant FS as File System

    Server->>Server: CleanupOldBinary()
    Server->>GitHub: GET /repos/:owner/:repo/releases/latest
    GitHub-->>Server: Release metadata + asset URLs
    alt Update available
        Server->>GitHub: Download binary asset
        Server->>FS: Write to .tmp staging file
        Server->>FS: Rename current → .old
        Server->>FS: Rename .tmp → current path
        alt Unix
            Server->>Server: syscall.Exec(self) — seamless re-exec
        else Windows
            Server->>Server: Update takes effect on next restart
        end
    else Up to date
        Server->>Server: Log "server is up to date"
    end

Startup check (stdio mode)

In stdio mode (the default), auto-update runs as a pre-start check with a 15-second timeout before the MCP server begins accepting connections:

CleanupOldBinary() removes any leftover .old file from a previous update
Checks for a newer release on GitHub
If mode is true and a newer version exists, downloads and replaces the binary
On Linux/macOS: re-executes via syscall.Exec() — same PID, same stdin/stdout pipes, no interruption to the MCP client
On Windows: logs that the update will take effect on next restart

The startup check is non-fatal — any error (network timeout, missing releases) is logged as a warning and does not prevent the server from starting.

Periodic check (HTTP mode)

In HTTP mode, auto-update runs as a background periodic check:

A goroutine checks for updates every AUTO_UPDATE_INTERVAL (default: 1 hour)
Each cycle checks GitHub for a newer release with a 30-second timeout
If mode is true, applies the update and logs a restart advisory
The goroutine stops when the server shuts down

Configuration

Environment variables (stdio mode)

Variable	Default	Description
`AUTO_UPDATE`	`true`	Update mode: `true`, `check`, or `false`
`AUTO_UPDATE_REPO`	`jmrplens/gitlab-mcp-server`	GitHub repository slug (`owner/repo`) for release assets
`AUTO_UPDATE_INTERVAL`	`1h`	Check interval (used by HTTP mode periodic checks)

CLI flags (HTTP mode)

Flag	Default	Description
`--auto-update`	`true`	Update mode: `true`, `check`, or `false`
`--auto-update-repo`	`jmrplens/gitlab-mcp-server`	GitHub repository slug (`owner/repo`) for release assets
`--auto-update-interval`	`1h`	Interval between periodic update checks

Configuration examples

Disable auto-update entirely:

AUTO_UPDATE=false

Check-only mode (log availability but do not apply):

AUTO_UPDATE=check

Use a custom fork repository:

AUTO_UPDATE_REPO=my-org/my-gitlab-mcp-fork

Shutdown flag for external updaters

External tools (such as pe-agnostic-store) can terminate all running instances before replacing the binary on disk:

gitlab-mcp-server --shutdown

This flag:

Finds all running gitlab-mcp-server processes by name
Sends a graceful termination signal
Waits up to 5 seconds for processes to exit
Force-kills any remaining processes
Exits — no MCP server is started

No admin or root permissions are required. This works on Linux, macOS, and Windows.

Rollback

If an update causes issues:

The previous binary is preserved as gitlab-mcp-server.old (or .exe.old on Windows) next to the current binary
To rollback, stop the server and rename the .old file back to the original name
The .old file is automatically cleaned up on the next successful startup

Custom repository support

You can point auto-update at any GitHub repository that follows the expected release format:

Set AUTO_UPDATE_REPO=owner/repo to your repository
Create GitHub releases with platform binaries named gitlab-mcp-server-{os}-{arch}
Include a checksums.txt asset with SHA-256 hashes (goreleaser format)