Glosario

Estos son los términos de esta documentación que son propios de GitLab MCP Server o del Model Context Protocol. Cada definición se sostiene por sí sola, así que puedes leer solo la que necesites.

Una superficie de herramientas es el conjunto de herramientas MCP que un cliente ve realmente al arrancar. GitLab MCP Server tiene tres, seleccionables con TOOL_SURFACE:

Superficie	Herramientas visibles	Se elige con
Dinámica (predeterminada)	2	TOOL_SURFACE=dynamic, o dejarlo sin definir
Meta-herramientas	32 herramientas de dominio (más con Enterprise)	TOOL_SURFACE=meta
Individual	847–1071	TOOL_SURFACE=individual

Las tres son proyecciones del mismo catálogo de acciones, así que difieren en empaquetado y coste de tokens, nunca en capacidad. Ver visión general de herramientas.

El catálogo canónico de acciones es la definición interna única de cada operación de GitLab que expone el servidor. Cada entrada lleva su ruta, esquemas de entrada y salida, clasificación de destructividad y tier de licencia. Todas las superficies visibles se generan desde este catálogo, y por eso el comportamiento y la seguridad son idénticos use el cliente la superficie que use.

Un ID canónico de acción identifica una operación, escrito domain.action — por ejemplo issue.list o merge_request.approve. El modo dinámico los devuelve desde gitlab_find_action y los ejecuta con gitlab_execute_action.

Una meta-herramienta es una herramienta MCP a nivel de dominio que agrupa operaciones relacionadas tras una sola herramienta con un parámetro action. gitlab_issue, por ejemplo, atiende list, get, create, update y delete. Reducen el número de herramientas visibles en más de un 95% manteniendo cada operación accesible como acción. Ver meta-herramientas.

El modo dinámico es la superficie predeterminada, y expone solo gitlab_find_action y gitlab_execute_action. El asistente busca en el catálogo la operación que necesita, recibe su esquema exacto y la ejecuta. Cuesta una llamada de descubrimiento por tarea y mantiene el contexto de arranque unas 444× menor que registrar cada herramienta por separado. Ver conjunto dinámico.

El gating por tier registra solo las acciones y campos de esquema que soporta la licencia de GitLab conectada. El tier sale de GITLAB_TIER si está definido; si no, se detecta de la licencia de la instancia, con Free como reserva. Los esquemas de entrada se podan de forma estricta, para que un tier inferior nunca vea campos superiores; los de salida se podan de forma laxa, para que los datos sigan llegando al cliente.

Safe mode (GITLAB_SAFE_MODE=true) intercepta cada llamada mutante y devuelve una previsualización JSON de lo que ocurriría, en vez de ejecutarla. Se distingue del modo solo lectura, que elimina las operaciones por completo en lugar de previsualizarlas.

El modo solo lectura (GITLAB_READ_ONLY=true) omite del catálogo registrado toda acción mutante. El asistente no puede llamar a una operación de escritura porque no existe en su lista — una garantía más fuerte que rechazar la llamada al ejecutarla.

La elicitación es una capacidad MCP que permite al servidor pedir datos al usuario mediante un formulario estructurado a mitad de conversación, en lugar de exigir todos los parámetros por adelantado. GitLab MCP Server la usa en flujos interactivos de creación y recurre a herramientas parametrizadas estándar en clientes que no la soportan. Ver elicitación.

La superficie de capacidades decide qué recursos y prompts MCP se registran, y se selecciona con CAPABILITY_SURFACE. full los registra todos; minimal registra solo el manifiesto gitlab://tools, recortando el contexto compartido de arranque de unos 31.800 tokens a unos 1.100 sin perder el descubrimiento de esquemas por acción.

Los recursos de manifiesto son gitlab://tools y gitlab://tools/{id}. El primero lista cada herramienta visible y acción ejecutable de la superficie activa; el segundo devuelve la forma de llamada aceptada y el JSON Schema de una acción. Ambos siguen disponibles con una superficie de capacidades mínima, y así un cliente descubre los parámetros exactos sin inflar la lista de herramientas.

Una acción destructiva es la que el catálogo clasifica como irreversible o con pérdida de datos: borrar un proyecto, eliminar artefactos de un job. Requieren confirmación explícita antes de ejecutarse, y el modo dinámico además suprime las coincidencias difusas débiles para ellas, de modo que una errata no pueda seleccionarlas.

El transporte stdio es el predeterminado: el cliente de IA arranca el servidor como proceso hijo e intercambia JSON-RPC por stdin y stdout. El token se pasa como variable de entorno, nunca sale de la máquina local y no hay exposición de red.

El transporte HTTP es el modo multiusuario: un proceso atiende a muchos clientes por red, cada uno autenticándose con su propio token de GitLab. Las sesiones se aíslan en un pool LRU acotado indexado por un hash de token y URL de GitLab, así que no se comparte estado entre clientes. Ver modo servidor HTTP.

Los tokens de esquema de herramientas son el coste en tokens de las definiciones visibles que el cliente recibe en cada tools/list: esquemas de entrada, anotaciones y descripciones. Es la cifra que diferencia unas superficies de otras. Se mide con el tokenizador {footprint.tokenizer} y excluye recursos y prompts MCP, que se contabilizan aparte como tokens compartidos.