Progreso
GitLab MCP Server envía notificaciones de progreso en tiempo real durante operaciones de larga duración, para que los clientes MCP puedan mostrar indicadores de progreso al usuario en lugar de una espera opaca. Cuando una herramienta abarca varios pasos, transmite una carga grande o sondea GitLab, el servidor emite mensajes notifications/progress que informan de cuánto ha avanzado el trabajo.
El progreso es de mejor esfuerzo: mejora la experiencia de usuario pero nunca es obligatorio para la corrección. Los clientes que no pueden mostrar el progreso ignoran silenciosamente las notificaciones, y la herramienta devuelve igualmente su resultado completo con normalidad.
¿Cómo funciona el reporte de progreso?
Sección titulada «¿Cómo funciona el reporte de progreso?»Cuando una herramienta realiza múltiples pasos, transmite una carga grande o sondea GitLab, el servidor envía mensajes notifications/progress al cliente a medida que avanza el trabajo. El cliente suministra un token de progreso con la llamada a la herramienta; cada mensaje lleva ese token, de modo que el cliente puede asociar la actualización a la solicitud correcta y mostrar un indicador de progreso mientras se sigue ensamblando el resultado final. Una llamada sin token no recibe notificaciones y por lo demás se comporta igual.
Los bytes miden la lectura, no la transferencia. El cliente de GitLab ensambla el cuerpo completo de la petición en memoria antes de enviar nada, así que todos los avisos se han emitido ya cuando el primer byte llega a la red, y la transferencia en sí no informa de nada hasta que termina.
¿Cuándo envía el servidor actualizaciones de progreso?
Sección titulada «¿Cuándo envía el servidor actualizaciones de progreso?»El reporte de progreso se utiliza para operaciones que pueden tardar varios segundos. En cada caso, la notificación describe lo que el servidor está haciendo en ese momento, de modo que el usuario percibe movimiento en lugar de una llamada bloqueada. Las herramientas simples de una sola petición como branch.list se completan demasiado rápido para informar de nada.
| Operación | Detalle del Progreso |
|---|---|
| Subida de archivos | Contado en bytes mientras project.upload lee el contenido y prepara la petición |
| Publicación de paquetes | Contando bytes mientras el archivo del paquete se transmite al registro |
| Acciones de espera | Cada sondeo de pipeline.wait y job.wait hasta que el pipeline o el job se asienta |
| Asistentes interactivos | Un paso por pregunta en los cuatro flujos gitlab_interactive_*, y después la creación |
¿Cómo muestran el progreso los clientes?
Sección titulada «¿Cómo muestran el progreso los clientes?»La forma en que se muestra el progreso depende del cliente MCP; el servidor emite las mismas notificaciones en todos los casos, y cada cliente las renderiza en su propia interfaz:
- VS Code / Copilot — Indicador de progreso en la barra de estado o panel de salida
- Claude Desktop — Texto de progreso mostrado durante la ejecución de la herramienta
- Claude Code — Actualizaciones de progreso en tiempo real en la terminal
¿Qué contiene una notificación de progreso?
Sección titulada «¿Qué contiene una notificación de progreso?»Las notificaciones de progreso siguen el formato JSON-RPC del protocolo MCP. El objeto params lleva cuatro campos que, en conjunto, permiten a un cliente renderizar una barra de progreso o una línea de estado.
{ "jsonrpc": "2.0", "method": "notifications/progress", "params": { "progressToken": "tool-call-123", "progress": 1048576, "total": 5242880, "message": "Read 1048576 / 5242880 bytes, preparing the upload" }}| Campo | Descripción |
|---|---|
progressToken | ID de correlación que vincula el progreso con la llamada original a la herramienta, suministrado por el cliente |
progress | Progreso hasta ahora; las herramientas por pasos cuentan desde 0 (el paso 1 de 3 envía 0), y el valor solo aumenta |
total | Cantidad total de trabajo (cuando se conoce) |
message | Descripción legible del paso actual |
Preguntas frecuentes
¿Qué son las notificaciones de progreso MCP?
Las notificaciones de progreso son mensajes de estado en tiempo real que GitLab MCP Server envía durante operaciones de larga duración para que los clientes MCP puedan mostrar el progreso al usuario. Cuando una herramienta ejecuta varios pasos, transmite una carga grande o sondea GitLab (subidas de archivos, publicación de paquetes, las acciones de espera de pipeline y job, los asistentes interactivos), el servidor emite mensajes notifications/progress que informan del paso actual, del total cuando se conoce y de una descripción legible. El progreso es de mejor esfuerzo, así que los clientes que no pueden mostrarlo ignoran los mensajes y la herramienta se completa igualmente.
¿Cuándo envía GitLab MCP Server actualizaciones de progreso?
GitLab MCP Server envía actualizaciones de progreso para operaciones que pueden tardar varios segundos: subidas de archivos (project.upload, contando bytes mientras se lee el contenido y se prepara la petición), publicación de paquetes (contando bytes mientras el archivo se transmite), las acciones de espera que sondean GitLab hasta que un pipeline o un job se asienta, y los cuatro asistentes interactivos (un paso por pregunta, y después la creación final). Cada notificación lleva un progressToken que la correlaciona con la llamada original a la herramienta; una llamada sin token no recibe notificaciones y por lo demás se comporta igual.
¿Qué contiene una notificación de progreso?
Una notificación de progreso sigue el formato JSON-RPC notifications/progress y lleva cuatro campos en sus params: progressToken (el ID de correlación que el cliente suministró con la llamada a la herramienta), progress (cuánto ha avanzado el trabajo, un valor que solo aumenta; las herramientas por pasos cuentan desde 0), total (la cantidad total de trabajo, cuando se conoce) y message (una descripción legible como "Read 1048576 / 5242880 bytes, preparing the upload"). Los clientes los usan para renderizar barras de progreso o texto de estado.
¿Qué ocurre si mi cliente no admite las notificaciones de progreso?
Las notificaciones de progreso son de mejor esfuerzo. Si el cliente MCP no admite la visualización de progreso, las notificaciones se ignoran silenciosamente y la herramienta se completa con normalidad con su resultado completo. No hace falta ninguna configuración y no se pierde funcionalidad — el progreso es puramente una mejora de la experiencia de usuario sobre la respuesta normal de la herramienta.