Visión general de herramientas

GitLab MCP Server expone las operaciones de GitLab como herramientas MCP que los asistentes de IA pueden invocar directamente. Ofrece tres modos de herramientas: dinámico, meta-herramientas e individual. Los tres alcanzan la misma superficie de API de GitLab. Solo cambian en el empaquetado, así que la elección equilibra coste de contexto y granularidad de la lista, nunca capacidad.

Cada modo se proyecta desde un único catálogo canónico de acciones. Eso da a los tres los mismos handlers, esquemas tipados y comportamiento de seguridad. Lo único que cambia es la presentación. El modo dinámico busca y ejecuta IDs canónicos domain.action. El modo meta-herramientas agrupa acciones por dominio. El modo individual registra una herramienta por operación.

El modo dinámico es el predeterminado y la opción adecuada para la mayoría de los asistentes. Mantiene dos herramientas en el contexto del modelo y aun así alcanza cualquier operación de GitLab. Elige el modo meta-herramientas cuando tu cliente funcione mejor con una lista fija de herramientas a nivel de dominio. Elige el modo individual solo cuando un cliente necesite enumerar por adelantado todas las operaciones.

Define el modo con la variable de entorno GITLAB_MCP_TOOL_SURFACE (dynamic, meta o individual). El modo dinámico se usa cuando GITLAB_MCP_TOOL_SURFACE no está definido.

El modo individual registra una herramienta MCP por operación de GitLab: 865 herramientas para CE, 1085 herramientas para Enterprise/Premium autoalojado, o 1091 herramientas en GitLab.com Enterprise/Premium cuando Orbit está disponible. Esto ofrece al asistente la máxima granularidad —cada operación es una herramienta distinta y descrita individualmente— a costa de un consumo significativo de tokens de contexto al listar y desambiguar herramientas durante el descubrimiento.

Qué expone

una herramienta MCP visible por operación de GitLab, cada una con su esquema tipado de entrada y salida — el catálogo completo, en plano.

Requiere

GITLAB_MCP_TOOL_SURFACE=individual, y un cliente con presupuesto de contexto para sostener la lista completa.

Efecto del tier

el propio número de herramientas se mueve con la licencia: Free/CE registra el catálogo base, Premium y Ultimate añaden sus herramientas restringidas, y los tiers inferiores nunca ven campos de entrada de tiers superiores en los esquemas.

Qué no hace

un arranque de bajo coste de tokens: listar cada herramienta es el propósito de esta superficie, así que el coste de descubrimiento no se puede reducir sin cambiar de superficie. Los clientes con ventanas de contexto pequeñas deberían usar la dinámica por defecto.

El modo meta-herramientas (GITLAB_MCP_TOOL_SURFACE=meta) consolida operaciones relacionadas en meta-herramientas a nivel de dominio. Cada meta-herramienta acepta un parámetro action que enruta al handler apropiado, reduciendo el recuento a 34 meta-herramientas base, 51 en Enterprise/Premium autoalojado, o 52 en GitLab.com Enterprise/Premium cuando Orbit está disponible. Esto mejora drásticamente la eficiencia de tokens frente al modo individual manteniendo una lista de herramientas fija y explorable.

{
  "tool": "gitlab_issue",
  "arguments": {
    "action": "create",
    "params": {
      "project_id": "my-group/my-project",
      "title": "Fix login redirect",
      "description": "Users are redirected to 404 after login",
      "labels": ["bug", "priority::high"]
    }
  }
}

Qué expone

una herramienta despachadora por dominio (proyectos, issues, merge requests, pipelines…), cada una enrutando un parámetro action a los mismos handlers que usan las demás superficies.

Requiere

GITLAB_MCP_TOOL_SURFACE=meta. Las formas de llamada por acción siguen siendo descubribles vía gitlab://tools y gitlab://tools/{id} sea cual sea el valor de GITLAB_MCP_META_PARAM_SCHEMA.

Efecto del tier

Premium/Ultimate añaden meta-herramientas enterprise dedicadas e inyectan rutas solo-enterprise en gitlab_project, gitlab_group y gitlab_issue.

Qué no hace

descripciones por operación en la lista de herramientas del cliente: una despachadora resume su dominio, así que un asistente que necesita el esquema exacto lo lee de los recursos del catálogo, no de tools/list.

El modo dinámico (GITLAB_MCP_TOOL_SURFACE=dynamic) es el predeterminado de bajo coste de tokens. Expone solo dos herramientas públicas —gitlab_find_action y gitlab_execute_action (el nombre en singular gitlab_execute_action es intencionado)— manteniendo cada acción de GitLab accesible a través del catálogo canónico. El asistente primero encuentra una acción y su esquema exacto, y luego ejecuta el ID canónico domain.action.

Como los tres modos comparten el catálogo canónico de acciones, el comportamiento de seguridad se mantiene coherente en todas las superficies: el filtrado de solo lectura, las vistas previas de modo seguro, el filtrado por alcance de token, las confirmaciones de acciones destructivas, los esquemas y el formato de resultados son idénticos.

Qué expone

dos herramientas — gitlab_find_action y gitlab_execute_action — que alcanzan el catálogo canónico completo: find devuelve esquemas exactos y execute ejecuta el domain.action canónico.

Requiere

nada: es el modo por defecto cuando GITLAB_MCP_TOOL_SURFACE no está definido. GITLAB_MCP_CAPABILITY_SURFACE=minimal reduce aún más la huella compartida de recursos y prompts.

Efecto del tier

invisible en tools/list (siempre dos herramientas) pero real en alcance: find solo muestra, y execute solo acepta, las acciones que el tier resuelto registra.

Qué no hace

una lista de herramientas explorable: el cliente ve dos herramientas, así que un humano que recorra tools/list no aprende nada sobre la cobertura — para eso están gitlab://tools y la herramienta find.

Todas las herramientas siguen un patrón de nombres coherente:

• Herramientas individuales: la forma predominante es gitlab_{domain}_{action} (p. ej., gitlab_issue_create, gitlab_project_list), primero el dominio; un conjunto heredado va con el verbo primero (gitlab_list_issue_discussions, gitlab_add_ssh_key), y cada nombre se declara en la especificación de catálogo de la acción en lugar de derivarse, así que léelo en gitlab://tools en vez de inferirlo
• Meta-herramientas: gitlab_{domain} (p. ej., gitlab_issue, gitlab_project)
• Acciones dinámicas: IDs canónicos domain.action ejecutados mediante gitlab_execute_action (p. ej., issue.create, merge_request.list)

Se registran cinco herramientas más junto a las meta-herramientas de dominio. Reciben sus parámetros directamente, sin envoltorio action, y conservan el mismo nombre en el modo individual:

Cuando el nivel resuelto es Premium o Ultimate, el servidor registra hasta 17 meta-herramientas autoalojadas adicionales para funciones de GitLab Premium y Ultimate. Seis llegan con Premium:

gitlab_audit_event, gitlab_enterprise_user, gitlab_geo, gitlab_group_scim, gitlab_merge_train, gitlab_project_alias

Once más llegan con Ultimate:

gitlab_attestation, gitlab_compliance_policy, gitlab_dependency, gitlab_dora_metrics, gitlab_external_status_check, gitlab_member_role, gitlab_security_attribute, gitlab_security_category, gitlab_security_finding, gitlab_security_scan_profile, gitlab_vulnerability

En GitLab.com con nivel Premium o Ultimate, el catálogo también registra gitlab_orbit con seis acciones de solo lectura del Knowledge Graph: status, schema, tools, dsl, query y graph_status.

Preguntas frecuentes

¿Cuál es la diferencia entre el modo meta-herramientas y el modo dinámico?

Tanto el modo meta-herramientas como el dinámico reducen el coste de tokens frente al modo individual, pero empaquetan las operaciones de forma distinta. El modo meta-herramientas expone una lista fija de 34 herramientas a nivel de dominio, cada una enrutando según un parámetro action —útil cuando un cliente funciona mejor con una lista de herramientas estable y explorable. El modo dinámico expone solo dos herramientas y resuelve las operaciones bajo demanda mediante búsqueda, ofreciendo la lista de herramientas más pequeña posible. Ambos comparten los mismos handlers y comportamiento de seguridad.

¿Todos los modos admiten las mismas operaciones de GitLab?

Sí. Los modos dinámico, meta-herramientas e individual se proyectan desde un único catálogo canónico de acciones, por lo que cubren las mismas operaciones REST y GraphQL de GitLab. Solo se diferencian en el empaquetado, no en la capacidad. El filtrado de solo lectura, las vistas previas de modo seguro, las confirmaciones de acciones destructivas, el filtrado por alcance de token y el formato de resultados se comportan de forma idéntica sea cual sea el modo que elijas.

¿Cuántas herramientas expone cada modo?

El modo individual expone 865 herramientas en CE, 1,085 en Enterprise/Premium autoalojado y 1,091 en GitLab.com cuando Orbit está disponible. El modo meta-herramientas expone 34 herramientas de dominio base (más con el catálogo Enterprise). El modo dinámico expone siempre exactamente dos herramientas públicas, sin importar cuántas operaciones de GitLab estén disponibles.

¿Las herramientas Enterprise requieren una licencia de GitLab de pago?

Sí. Las meta-herramientas Enterprise —como merge trains, métricas DORA, vulnerabilidades y políticas de cumplimiento— requieren una licencia de GitLab Premium o Ultimate en la instancia conectada. Forzar el catálogo Enterprise en una instancia Community Edition registra las herramientas, pero las llamadas a la API subyacente devuelven errores de permiso porque las funciones no están licenciadas.

¿Cuáles son los tres modos de herramientas de GitLab MCP Server?

GitLab MCP Server ofrece tres modos de herramientas que exponen la misma superficie de API de GitLab con distinto empaquetado. El modo dinámico (predeterminado) expone dos herramientas públicas que buscan y ejecutan un catálogo canónico de acciones. El modo meta-herramientas agrupa operaciones relacionadas en herramientas a nivel de dominio que enrutan según un parámetro de acción. El modo individual registra una herramienta MCP por operación de GitLab. Los tres modos comparten los mismos handlers, esquemas y comportamiento de seguridad.

¿Qué modo de herramientas es más eficiente en tokens?

El modo dinámico es el más eficiente en tokens porque expone solo dos herramientas públicas, sin importar cuántas operaciones de GitLab existan. El asistente primero llama a gitlab_find_action para obtener una acción y su esquema, y luego llama a gitlab_execute_action. Así la lista de herramientas se mantiene pequeña en la ventana de contexto del modelo y, a la vez, se alcanza cualquier operación de GitLab a través del catálogo de acciones compartido.

• Meta-herramientas — arquitectura detallada de meta-herramientas y uso
• Conjunto dinámico — modo de búsqueda, descripción y ejecución con bajo consumo de tokens
• Orbit — herramientas Knowledge Graph para GitLab.com Premium/Ultimate
• Recursos y prompts — contexto de solo lectura y plantillas de prompts

• Especificación del Model Context Protocol — el protocolo que implementan estas herramientas
• API REST v4 de GitLab — la superficie REST que llama la mayoría de las herramientas
• API GraphQL de GitLab — la superficie GraphQL que usan el resto de dominios