Meta-herramientas

Las meta-herramientas son un modo de operación explícito de GitLab MCP Server, habilitado con GITLAB_MCP_TOOL_SURFACE=meta. En lugar de exponer cada operación de la API de GitLab como una herramienta MCP separada, las meta-herramientas agrupan operaciones relacionadas bajo una única herramienta con un parámetro action que despacha al handler correcto. El resultado es una lista de herramientas pequeña y explorable —un puñado de herramientas a nivel de dominio como gitlab_issue, gitlab_project y gitlab_pipeline— que aun así alcanza cualquier operación de GitLab.

¿Por qué usar meta-herramientas?

Las meta-herramientas existen para encajar una superficie completa de la API de GitLab en una ventana de contexto LLM limitada. Cuando un servidor MCP registra cientos de herramientas individuales (hasta 1091 en GitLab.com Enterprise/Premium con Orbit), solo las descripciones de las herramientas consumen una gran porción de los tokens disponibles, dejando menos espacio para la conversación real. El modo meta-herramientas colapsa esas operaciones en herramientas a nivel de dominio, así que la lista de herramientas se mantiene pequeña mientras la funcionalidad sigue completa.

Modo	Nº de herramientas	Overhead de tokens	Funcionalidad
Individual	865 / 1085 / 1091	Muy alto	Completa
Meta (base)	34	Bajo	Completa
Meta (enterprise)	51 / 52	Bajo	Completa + Premium/Ultimate

Las meta-herramientas reducen el recuento de herramientas en más del 95% mientras preservan el 100% de la funcionalidad. Cada operación de herramienta individual está disponible como una acción dentro de una de las meta-herramientas de dominio.

La herramienta de diagnóstico gitlab_server (acciones de solo lectura status y health_check) se registra por separado y no está incluida en los conteos 34/51/52 del catálogo de acciones GitLab.

¿Cómo funcionan las meta-herramientas?

Cada meta-herramienta define un enum action que lista todas las operaciones que admite, luego valida la acción elegida y la despacha a la función handler correspondiente internamente. El parámetro action siempre es requerido y debe ser uno de los valores enumerados; los parámetros adicionales dependen de la acción elegida. Por eso una sola herramienta como gitlab_issue puede cubrir un dominio entero sin exponer una herramienta separada por operación.

El parámetro action siempre es requerido y debe ser uno de los valores enumerados. Los parámetros adicionales dependen de la acción elegida.

¿Cómo descubro los parámetros por acción?

Las meta-herramientas usan un sobre común, y la forma exacta de params para cualquier acción se descubre a través del manifiesto de herramientas en lugar de incluirse en cada schema de herramienta. Por defecto, GITLAB_MCP_META_PARAM_SCHEMA=opaque mantiene pequeño el schema de la herramienta: los clientes ven el enum válido de action, mientras params queda como un objeto específico de la acción.

{
  "action": "create",
  "params": {
    "project_id": "42"
  }
}

Para descubrir la forma exacta de una acción concreta, lee el manifiesto de herramientas:

Recurso	Uso
`gitlab://tools`	Lista herramientas visibles y entradas ejecutables para la superficie activa
`gitlab://tools/{id}`	Devuelve la forma de llamada aceptada y el JSON Schema de una acción, como `gitlab_project.get`

Ejemplos de lectura de recursos:

{
  "method": "resources/read",
  "params": {
    "uri": "gitlab://tools"
  }
}

{
  "method": "resources/read",
  "params": {
    "uri": "gitlab://tools/gitlab_merge_request.create"
  }
}

La respuesta del detalle por acción incluye el schema de params y la forma de llamada final. Estos recursos siguen disponibles para meta-herramientas cuando GITLAB_MCP_CAPABILITY_SURFACE=minimal está habilitado, mientras se omiten recursos opcionales de GitLab, prompts y guías de flujo. Los despliegues dinámicos pueden seguir usando gitlab_find_action para schemas inline; los despliegues de meta-herramientas pueden mantener GITLAB_MCP_META_PARAM_SCHEMA=opaque y leer gitlab://tools/{id} en vez de incluir schemas en tools/list. Hoy compact ocupa unas 8 veces lo que opaque y full unas 18 veces; vuelve a medirlo con go run ./cmd/audit_tokens --compare-schemas.

Ejemplos de uso

Crear un issue

{
  "tool": "gitlab_issue",
  "arguments": {
    "action": "create",
    "params": {
      "project_id": "my-group/my-project",
      "title": "Update API documentation",
      "description": "The REST API docs are missing the new v2 endpoints",
      "labels": ["documentation", "api"],
      "assignee_ids": [42],
      "milestone_id": 7
    }
  }
}

Listar merge requests

{
  "tool": "gitlab_merge_request",
  "arguments": {
    "action": "list",
    "params": {
      "project_id": "my-group/my-project",
      "state": "opened",
      "order_by": "updated_at",
      "per_page": 20
    }
  }
}

Buscar código

{
  "tool": "gitlab_search",
  "arguments": {
    "action": "code",
    "params": {
      "query": "func handleWebhook",
      "project_id": "my-group/my-project"
    }
  }
}

Comprobar disponibilidad de Orbit

{
  "tool": "gitlab_orbit",
  "arguments": {
    "action": "status",
    "params": {
      "response_format": "llm"
    }
  }
}

gitlab_orbit solo se registra para conexiones con https://gitlab.com en el nivel Premium o Ultimate y expone seis acciones de solo lectura del Knowledge Graph: status, schema, tools, dsl, query y graph_status.

Referencia de meta-herramientas clave

Las listas de acciones siguientes son una selección representativa, no el conjunto completo. gitlab://tools lista todas las herramientas visibles y entradas ejecutables de la superficie activa, y gitlab://tools/{id} devuelve la lista completa de acciones y el JSON Schema de una de ellas.

`gitlab_project`

Ciclo de vida y configuración de proyectos, además de las etiquetas, hitos, miembros, badges, boards, integraciones y subidas con alcance de proyecto.

Acciones: list, get, create, update, delete, restore, archive, unarchive, fork, star, unstar, transfer, languages, list_users, list_forks, list_starrers, hook_list, hook_add, hook_edit, hook_delete, label_*, milestone_*, members, member_*, badge_*, board_*, upload

`gitlab_issue`

Ciclo de vida completo de incidencias, incluidas notas, discusiones, enlaces y seguimiento de tiempo.

Acciones: list, list_all, list_group, get, create, update, delete, move, reorder, subscribe, unsubscribe, create_todo, participants, time_estimate_set, spent_time_add, note_*, discussion_*, link_*

`gitlab_merge_request`

Flujo de trabajo completo de merge requests desde la creación hasta el merge.

Acciones: list, list_global, list_group, get, create, update, merge, rebase, approve, unapprove, subscribe, unsubscribe, commits, pipelines, reviewers, participants, cancel_auto_merge, approval_*, time_estimate_set, spent_time_add

`gitlab_mr_review`

La superficie de revisión de merge requests: notas, discusiones en hilo, notas en borrador y diffs.

Acciones: note_list, note_get, note_create, note_update, note_delete, discussion_list, discussion_get, discussion_create, discussion_reply, discussion_resolve, draft_note_*, changes_get, raw_diffs, diff_versions_list, diff_version_get

`gitlab_pipeline`

Gestión y seguimiento de pipelines, además de schedules y tokens de trigger.

Acciones: list, get, latest, create, cancel, retry, delete, variables, test_report, test_report_summary, update_metadata, wait, schedule_*, trigger_*

`gitlab_job`

Gestión de jobs de CI/CD.

Acciones: list, list_project, get, play, cancel, retry, erase, trace, artifacts, download_artifacts, keep_artifacts, delete_artifacts, delete_project_artifacts, list_bridges, wait

`gitlab_branch`

Operaciones de ramas y reglas de protección.

Acciones: list, get, create, delete, delete_merged, protect, unprotect, list_protected, get_protected, update_protected

`gitlab_repository`

Árbol del repositorio, archivos, commits, diffs e historial. Los commits no tienen meta-herramienta propia: sus operaciones son acciones de esta.

Acciones: tree, compare, merge_base, contributors, blob, raw_blob, archive, changelog_generate, changelog_add, file_get, file_create, file_update, file_delete, file_blame, file_raw, commit_list, commit_get, commit_diff, commit_refs, commit_cherry_pick, commit_revert, commit_comments, commit_comment_create, commit_statuses, commit_merge_requests

`gitlab_tag`

Gestión de etiquetas (tags) y reglas de protección.

Acciones: list, get, create, delete, get_signature, protect, unprotect, list_protected, get_protected

`gitlab_release`

Ciclo de vida de releases y enlaces de activos de release.

Acciones: list, get, get_latest, create, update, delete, link_list, link_get, link_create, link_create_batch, link_update, link_delete

Etiquetas, hitos y miembros

Las etiquetas, los hitos y los miembros no tienen meta-herramienta propia. Son acciones de las meta-herramientas de proyecto y de grupo:

A través de gitlab_project: label_list, label_get, label_create, label_update, label_delete, label_subscribe, label_unsubscribe, label_promote, milestone_list, milestone_get, milestone_create, milestone_update, milestone_delete, milestone_issues, milestone_merge_requests, members, member_get, member_add, member_edit, member_delete
A través de gitlab_group: las mismas operaciones con el prefijo group_ — group_label_*, group_milestone_*, group_member_*

`gitlab_group`

Gestión de grupos y subgrupos.

Acciones: list, get, create, update, delete, restore, archive, unarchive, projects, subgroups, members, shared_with, invited_groups, transfer, transfer_project, share_with_group, unshare_from_group, hook_*

`gitlab_search`

Búsqueda entre recursos en toda tu instancia de GitLab.

Acciones: code, issues, merge_requests, commits, milestones, notes, projects, snippets, users, wiki

`gitlab_user`

Información y búsqueda de usuarios, más la lista de tareas pendientes del usuario autenticado, que no tiene meta-herramienta propia.

Acciones: current, get, list, create, modify, get_status, set_status, ssh_keys, emails, contribution_events, block, unblock, ban, unban, activate, deactivate, todo_list, todo_mark_done, todo_mark_all_done

`gitlab_wiki`

Gestión de páginas wiki.

Acciones: list, get, create, update, delete, upload_attachment

Modo Enterprise

El catálogo Enterprise/Premium habilita 17 meta-herramientas adicionales que exponen funciones de GitLab Premium y Ultimate: seis llegan con Premium (40 herramientas) y once más con Ultimate (51). En modo stdio, establece GITLAB_MCP_TIER=premium o GITLAB_MCP_TIER=ultimate; en modo HTTP, usa --tier=premium (o --tier=ultimate) para forzar el catálogo, u omítelo para permitir la autodetección desde la licencia de la instancia por entrada token+URL. La variable booleana heredada GITLAB_ENTERPRISE=true sigue respetándose como alternativa cuando GITLAB_MCP_TIER no está definido, pero está deprecada. El modo HTTP también lee ambas variables de su entorno, pero solo cuando --tier no se pasa en la línea de comandos. El tier también poda entradas de esquema por campo mediante pruneSchemaFieldsByTier (ver internal/tools/action_catalog.go). Además, se añaden rutas de acción solo enterprise a las meta-herramientas base existentes:

Iterations → enrutadas a través de gitlab_issue
Project mirrors → enrutadas a través de gitlab_project
SSH certificates → enrutadas a través de gitlab_group
Security settings → divididas entre gitlab_project y gitlab_group
Group credentials → enrutadas a través de gitlab_group
Group analytics → enrutadas a través de gitlab_group

Configuración

Variable	Predeterminado	Descripción
`GITLAB_MCP_TOOL_SURFACE`	`dynamic`	Selector canónico: usa `meta` para meta-herramientas. Usa `individual` solo cuando quieras deliberadamente una herramienta MCP por operación de GitLab; sin definir, se usa la superficie dinámica predeterminada.
`GITLAB_MCP_CAPABILITY_SURFACE`	`full`	Selector del catálogo de recursos y prompts: `full` o `minimal`. Minimal mantiene el manifiesto `gitlab://tools`, y omite recursos opcionales, guías y prompts.
`GITLAB_MCP_META_PARAM_SCHEMA`	`opaque`	Controla cuánto schema de `params` por acción se incluye en `tools/list`: `opaque`, `compact` o `full`. Los schemas exactos están disponibles con `gitlab://tools/{id}`.
`GITLAB_MCP_TIER`	(autodetectado)	Selector de edición: `free`/`ce`, `premium` o `ultimate`. Cuando se omite, el tier se detecta desde `GET /license` (por defecto `free`). Reemplaza al flag deprecado `GITLAB_ENTERPRISE`.
`--tier`	(autodetectado)	Flag de edición en modo HTTP: `free`/`ce`, `premium` o `ultimate`. Cuando no se pasa, se usa en su lugar `GITLAB_MCP_TIER` (o el deprecado `GITLAB_ENTERPRISE`) del entorno.

Metadatos de descubrimiento

Cada acción de meta-herramienta lleva metadatos de descubrimiento (alias, uso, guía de parámetros, acciones relacionadas) que ayudan a los modelos a elegir la acción correcta y a dar forma a los parámetros. Ejecuta go run ./cmd/audit_discovery_completeness/ para puntuar el catálogo; el auditor produce un backlog priorizado que usan los agentes de dominio para rellenar carencias siguiendo el estándar de oro link-create-batch.

Preguntas frecuentes

¿Qué es el parámetro action?

El parámetro action es el campo requerido en cada meta-herramienta. Cada meta-herramienta define un enum action que lista las operaciones que admite, y el servidor valida la acción elegida antes de despachar al handler correspondiente. Por ejemplo, gitlab_issue acepta list, get, create, update, delete y más. El action siempre es requerido y debe ser uno de los valores enumerados; el resto de parámetros van bajo params y dependen de la acción que elijas.

¿Cuánto reducen las meta-herramientas el número de herramientas?

Las meta-herramientas reducen el recuento de herramientas registradas en más del 95% manteniendo el 100% de la funcionalidad. El modo individual puede registrar cientos de herramientas —865 en CE, hasta 1,091 en GitLab.com Enterprise/Premium con Orbit—, mientras que el modo meta-herramientas expone 34 herramientas de dominio base (más con el catálogo Enterprise). Cada operación individual sigue siendo accesible como una acción dentro de una meta-herramienta de dominio, así que no se pierde ninguna capacidad; solo cae drásticamente el overhead de tokens de la lista de herramientas.

¿Cómo encuentro los parámetros exactos de una acción?

Por defecto, GITLAB_MCP_META_PARAM_SCHEMA=opaque mantiene pequeño el schema de cada meta-herramienta, así que la forma exacta de params se descubre a través del manifiesto de herramientas. Lee gitlab://tools para listar las herramientas visibles y entradas ejecutables de la superficie activa, y luego lee gitlab://tools/{id} —por ejemplo gitlab://tools/gitlab_merge_request.create— para obtener la forma de llamada aceptada y el JSON Schema de una acción. Estos recursos de manifiesto siguen disponibles incluso con GITLAB_MCP_CAPABILITY_SURFACE=minimal. Los despliegues dinámicos pueden usar en su lugar gitlab_find_action para schemas inline.

¿Cómo habilito las meta-herramientas Enterprise?

El catálogo Enterprise/Premium eleva el número de meta-herramientas de 34 a 40 en Premium y a 51 en Ultimate en una instancia autoalojada, añadiendo herramientas para funciones de GitLab Premium y Ultimate. En modo stdio, establece GITLAB_MCP_TIER=premium o GITLAB_MCP_TIER=ultimate; en modo HTTP, usa --tier=premium (o --tier=ultimate) para forzar el catálogo, u omítelo para permitir la autodetección desde la licencia de la instancia por entrada token+URL. La variable de entorno heredada GITLAB_ENTERPRISE=true sigue respetándose como alternativa cuando GITLAB_MCP_TIER no está definido, pero está deprecada; el modo HTTP lee esas mismas dos variables de su entorno cuando no se pasa --tier. Habilitar el tier también añade rutas solo enterprise (como iterations, project mirrors y SSH certificates) a las meta-herramientas base existentes.

¿Por qué algunos clientes necesitan el modo meta-herramientas?

Algunos clientes de IA imponen límites en el número de herramientas; por ejemplo, JetBrains AI Assistant limita los servidores MCP a 100 herramientas. El modo meta-herramientas mantiene la lista visible de herramientas dentro de esas restricciones porque consolida cientos de operaciones en 34 herramientas de dominio base (o 51/52 con el catálogo Enterprise). Si en su lugar seleccionas herramientas individuales con GITLAB_MCP_TOOL_SURFACE=individual, los clientes con dichos límites solo verán un subconjunto del conjunto completo de herramientas individuales, ocultando algunas operaciones.

¿Qué son las meta-herramientas de GitLab MCP Server?

Las meta-herramientas son un modo de operación explícito de GitLab MCP Server, habilitado con GITLAB_MCP_TOOL_SURFACE=meta. En lugar de exponer cada operación de la API de GitLab como una herramienta MCP separada, una meta-herramienta agrupa operaciones relacionadas bajo una única herramienta a nivel de dominio con un parámetro action que despacha al handler correcto. Por ejemplo, gitlab_issue gestiona list, get, create, update y delete a través de una sola herramienta. Cada operación de herramienta individual sigue disponible como una acción dentro de una de las meta-herramientas de dominio, así que la funcionalidad no cambia.

Referencia de la fuente

Mantenido por José Manuel Requena PlensGitHub LinkedIn Mastodon Google Scholar Todos los proyectos