Progress
GitLab MCP Server sends real-time progress notifications during long-running operations, so MCP clients can display progress indicators to the user instead of an opaque wait. When a tool spans multiple steps, streams a large payload or polls GitLab, the server emits notifications/progress messages that report how far along the work is.
Progress is best-effort: it enhances the user experience but is never required for correctness. Clients that cannot display progress silently ignore the notifications, and the tool still returns its full result normally.
How does progress reporting work?
Section titled “How does progress reporting work?”When a tool performs multiple steps, streams a large payload or polls GitLab, the server sends notifications/progress messages to the client as the work advances. The client supplies a progress token with the tool call; each message carries that token, so the client can attach the update to the right request and render a progress indicator while the final result is still being assembled. A call without a token gets no notifications and behaves identically otherwise.
The byte counts measure the read, not the transfer. The GitLab client assembles the whole request body in memory before it sends anything, so every frame has already fired by the time the first byte reaches the network, and the transfer itself reports nothing until it returns.
When does the server send progress updates?
Section titled “When does the server send progress updates?”Progress reporting is used for operations that may take several seconds. In each case the notification describes what the server is currently doing, so the user sees motion rather than a stalled call. Simple single-request tools such as branch.list complete too quickly to report anything.
| Operation | Progress Detail |
|---|---|
| File upload | Byte-counted while project.upload reads the content and prepares the request |
| Package publishing | Byte-counted while the package file streams to the registry |
| Wait actions | Each poll of pipeline.wait and job.wait until the pipeline or job settles |
| Interactive wizards | One step per prompt in the four gitlab_interactive_* flows, then the creation |
How do clients display progress?
Section titled “How do clients display progress?”How progress is displayed depends on the MCP client; the server emits the same notifications regardless, and each client renders them in its own UI:
- VS Code / Copilot — Progress indicator in the status bar or output panel
- Claude Desktop — Progress text shown during tool execution
- Claude Code — Real-time terminal progress updates
What does a progress notification contain?
Section titled “What does a progress notification contain?”Progress notifications follow the MCP protocol’s JSON-RPC format. The params object carries four fields that together let a client render a progress bar or status line.
{ "jsonrpc": "2.0", "method": "notifications/progress", "params": { "progressToken": "tool-call-123", "progress": 1048576, "total": 5242880, "message": "Read 1048576 / 5242880 bytes, preparing the upload" }}| Field | Description |
|---|---|
progressToken | Correlation ID linking progress to the original tool call, supplied by the client |
progress | Progress so far; step-based tools count from 0 (step 1 of 3 sends 0), and the value only ever increases |
total | Total amount of work (when known) |
message | Human-readable description of the current step |
Frequently asked questions
What are MCP progress notifications?
Progress notifications are real-time status messages that GitLab MCP Server sends during long-running operations so MCP clients can show progress to the user. When a tool runs multiple steps, streams a large payload or polls GitLab (file uploads, package publishing, the pipeline and job wait actions, the interactive wizards), the server emits notifications/progress messages reporting the current step, the total when known, and a human-readable description. Progress is best-effort, so clients that cannot display it ignore the messages and the tool still completes.
When does GitLab MCP Server send progress updates?
GitLab MCP Server sends progress updates for operations that may take several seconds: file uploads (project.upload, byte-counted while the content is read and the request prepared), package publishing (byte-counted while the file streams), the wait actions that poll GitLab until a pipeline or job settles, and the four interactive wizards (one step per prompt, then the final creation). Each notification carries a progressToken correlating it to the original tool call; a call without a token gets no notifications and behaves identically otherwise.
What does a progress notification contain?
A progress notification follows the JSON-RPC notifications/progress format and carries four fields in its params: progressToken (the correlation ID the client supplied with the tool call), progress (how far the work has come, a value that only increases; step-based tools count from 0), total (the total amount of work, when known), and message (a human-readable description such as "Read 1048576 / 5242880 bytes, preparing the upload"). Clients use these to render progress bars or status text.
What happens if my client does not support progress notifications?
Progress notifications are best-effort. If the MCP client does not support progress display, the notifications are silently ignored and the tool still completes normally with its full result. No configuration is needed and no functionality is lost — progress is purely a user-experience enhancement on top of the normal tool response.