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 reglas de seguridad, salvo en cómo se confirma una llamada destructiva. Por lo demás, solo cambia 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: 868 herramientas en Free/CE, 1022 herramientas en Premium autoalojado, 1088 herramientas en Ultimate autoalojado, o 1094 herramientas en GitLab.com Ultimate, donde 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 en Free/CE, 40 en Premium autoalojado, 51 en Ultimate autoalojado, o 52 en GitLab.com Ultimate, donde 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 y suman acciones a siete despachadores base: gitlab_project, gitlab_group, gitlab_issue, gitlab_merge_request, gitlab_environment, gitlab_storage_move y gitlab_runner.

Qué no hace

el esquema exacto de parámetros de cada acción en tools/list con el modo predeterminado opaque: la descripción de un despachador lleva una línea de guía por acción, y un asistente lee el esquema exacto de los recursos del catálogo (gitlab://tools/{id}) salvo que GITLAB_MCP_META_PARAM_SCHEMA sea compact o full.

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, las reglas de seguridad salen de un solo sitio: el filtrado de solo lectura, el modo seguro, el filtrado por alcance de token, la clasificación destructiva, los esquemas y el formato de resultados son los mismos en todas las superficies. Lo que difiere, en un solo punto, es cómo se confirma una llamada destructiva: la superficie dinámica nunca pregunta, así que exige confirm: true en cada una salvo que GITLAB_MCP_YOLO_MODE omita la confirmación, como hace en todas las superficies, según explica Acciones destructivas.

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)

Las 34 herramientas que sirve una instancia Free/CE son 28 despachadores de dominio, la herramienta de diagnóstico gitlab_server y cinco herramientas que reciben sus argumentos directamente. Premium y Ultimate añaden acciones a siete de estos despachadores; el número de acciones de cada uno en cada tier está en Meta-herramientas.

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, para 40 meta-herramientas (el número de acciones de cada una va entre paréntesis):

gitlab_audit_event (6), gitlab_enterprise_user (4, necesita admin_mode), gitlab_geo (8, necesita admin_mode), gitlab_group_scim (4), gitlab_merge_train (4), gitlab_project_alias (4, necesita admin_mode)

Once más llegan con Ultimate, para 51 en una instancia autoalojada:

gitlab_attestation (2), gitlab_compliance_policy (2), gitlab_dependency (4), gitlab_dora_metrics (2), gitlab_external_status_check (8), gitlab_member_role (6), gitlab_security_attribute (5), gitlab_security_category (3), gitlab_security_finding (1), gitlab_security_scan_profile (3), gitlab_vulnerability (8)

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. Eso da 52 meta-herramientas en GitLab.com Ultimate.

Un grupo que necesita admin_mode queda fuera para un token sin ese scope (Filtrado de herramientas por scopes). Lo que ambos tiers añaden a los despachadores base se detalla en Modo Enterprise.

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 herramientas (34 en Free/CE, hasta 52 en GitLab.com Ultimate), la mayoría a nivel de dominio y 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 las mismas reglas de seguridad, salvo en cómo se confirma una llamada destructiva.

¿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. Se diferencian en el empaquetado, no en la capacidad. El filtrado de solo lectura, el modo seguro, la clasificación destructiva, el filtrado por alcance de token y el formato de resultados son comunes a todos los modos. La única diferencia es cómo se confirma una llamada destructiva: la superficie dinámica por defecto nunca pregunta, así que exige confirm: true en cada una salvo que GITLAB_MCP_YOLO_MODE omita la confirmación, como hace en todas las superficies.

¿Cuántas herramientas expone cada modo?

El modo individual expone 868 herramientas en Free/CE, 1,022 en Premium autoalojado, 1,088 en Ultimate autoalojado y 1,094 en GitLab.com Ultimate, donde Orbit está disponible. El modo meta-herramientas expone 34 herramientas en Free/CE, 40 en Premium autoalojado, 51 en Ultimate autoalojado y 52 en GitLab.com Ultimate. 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 fallan: Community Edition no sirve esos endpoints y responde 404, y una Enterprise Edition sin licencia las rechaza.

¿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 tipados y reglas de seguridad, salvo en cómo se confirma una llamada destructiva.

¿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.

• Herramientas por dominio: cada acción de cada grupo del catálogo, con sus parámetros y el tier que necesita
• Meta-herramientas — arquitectura detallada de meta-herramientas y uso
• Conjunto dinámico: el modo de búsqueda 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
• Formato de salida: lo que lleva un resultado de herramienta, en Markdown y en JSON
• Línea de comandos y variables de entorno: cada ajuste que elige una superficie, un tier o un filtro

• 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