Visión general de herramientas

GitLab MCP Server expone las operaciones de GitLab como herramientas MCP que los asistentes de IA pueden invocar directamente. El servidor ofrece tres modos de operación para equilibrar capacidad con eficiencia de tokens.

Todos los modos cubren la misma superficie de API de GitLab. Cambia el empaquetado: el modo individual expone una herramienta MCP por operación, el modo meta-herramientas agrupa acciones por dominio, y el modo dinámico busca y ejecuta IDs canónicos domain.action desde el mismo catálogo de acciones.

Modos de operación

Modo individual

En modo individual, el servidor registra una herramienta por operación de GitLab: 863 herramientas para CE, 1006 herramientas para Enterprise/Premium autoalojado, o 1011 herramientas en GitLab.com Enterprise/Premium cuando Orbit está disponible. Esto proporciona la máxima granularidad pero consume una cantidad significativa de tokens de contexto del LLM para el descubrimiento de herramientas.

Modo meta-herramientas (predeterminado)

En modo meta-herramientas (META_TOOLS=true), las operaciones relacionadas se consolidan en meta-herramientas a nivel de dominio. Cada meta-herramienta acepta un parámetro action que enruta al handler apropiado. Esto reduce el recuento de herramientas a 32 meta-herramientas base, 47 en Enterprise/Premium autoalojado, o 48 en GitLab.com Enterprise/Premium cuando Orbit está disponible, mejorando drásticamente la eficiencia de tokens del LLM mientras se preserva toda la funcionalidad.

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

Conjunto de herramientas dinámico

El modo dinámico (TOOL_SURFACE=dynamic o TOOL_SURFACE=dynamic-3) es la alternativa de bajo consumo de tokens. Expone solo gitlab_search_tools, gitlab_describe_tools y gitlab_execute_tool, mientras conserva las mismas acciones de GitLab detrás del catálogo canónico. El asistente busca una acción, describe el schema exacto y luego ejecuta el ID canónico domain.action.

flowchart LR
	A[Buscar herramientas] --> B[Describir acción]
	B --> C[Ejecutar domain.action]
	C --> D[Handler existente de GitLab]

Como las meta-herramientas y el modo dinámico comparten el catálogo de acciones canónico, el comportamiento de seguridad es consistente entre ambos modos: filtrado de solo lectura, previsualizaciones de safe mode, filtrado por scopes del token, confirmaciones destructivas, schemas y formato de resultados se definen una vez y se reutilizan.

Convención de nombres de herramientas

Todas las herramientas siguen un patrón de nomenclatura consistente:

• Herramientas individuales: gitlab_{action}_{resource} (p. ej., gitlab_create_issue, gitlab_list_projects)
• Meta-herramientas: gitlab_{domain} (p. ej., gitlab_issue, gitlab_project)
• Acciones dinámicas: IDs canónicos domain.action ejecutados mediante gitlab_execute_tool (p. ej., issue.create, merge_request.list)

Meta-herramientas base (32)

Gestión de proyectos

Meta-herramienta	Descripción	Acciones principales
gitlab_project	CRUD de proyectos, configuración, hooks, etiquetas, milestones, miembros, badges, tokens de acceso, todos, upload, etc	list, get, create, update, delete, fork, star, archive, label_*, milestone_*, members, badge_*, upload
gitlab_issue	Ciclo de vida de issues, notas, discusiones, enlaces, work items, seguimiento de tiempo, award emoji y eventos	list, get, create, update, delete, note_*, link_*, discussion_*, work_item_*, time_*
gitlab_group	CRUD de grupos, subgrupos, miembros, badges, hooks, etiquetas, milestones, transferencia y proyectos descendientes	list, get, create, update, delete, label_*, milestone_*, member_*, badge_*, hook_*
gitlab_user	Información de usuarios, estado, claves SSH, claves GPG, emails, actividad y preferencias	get, current, list, ssh_key_*, gpg_key_*, email_*, status_*
gitlab_wiki	Gestión de páginas wiki y adjuntos	list, get, create, update, delete, upload_attachment

Código y repositorio

Meta-herramienta	Descripción	Acciones principales
gitlab_branch	Gestión de ramas y reglas de protección (incluyendo consultas de reglas de rama vía GraphQL)	list, get, create, delete, protect, unprotect, branch_rule_*
gitlab_tag	Gestión de tags y reglas de protección con verificación de firma GPG	list, get, create, delete, protect, unprotect
gitlab_release	Gestión de releases y enlaces de assets de release	list, get, create, update, delete, link_*
gitlab_repository	Árbol del repositorio, archivos, commits, diffs, blame, comparar, cherry-pick, revert, contribuidores, archivos y changelogs	tree, file_*, commit_*, compare, blame, archive, changelog, submodule_*, discussion_*
gitlab_merge_request	Ciclo de vida de MRs, aprobaciones, reglas de aprobación, seguimiento de tiempo, suscripciones, award emoji y eventos	list, get, create, update, merge, rebase, approve, approval_*, time_*, event_*

Revisión de código

Meta-herramienta	Descripción	Acciones principales
gitlab_mr_review	Notas de MR, discusiones con hilos, diffs de código, notas borrador y versiones	note_*, discussion_*, diff_*, draft_*, version_*

CI/CD

Meta-herramienta	Descripción	Acciones principales
gitlab_pipeline	Gestión de pipelines, grupos de recursos, informes de tests, trigger tokens, bridges y programaciones de pipelines	list, get, create, cancel, retry, delete, wait, schedule_*, trigger_*
gitlab_job	Gestión de jobs de CI, artefactos, logs y agentes de Kubernetes	list, get, play, cancel, retry, erase, trace, artifacts, wait, k8s_*
gitlab_runner	Gestión de runners de CI/CD, controladores de runners, scopes de controladores y tokens de controladores	list, get, update, remove, jobs, controller_*, register, verify
gitlab_ci_variable	Variables de CI/CD a nivel de instancia, grupo y proyecto	list, get, create, update, delete (en cada nivel de scope)
gitlab_environment	Gestión de entornos, entornos protegidos, periodos de congelamiento de despliegue y registros de despliegue	list, get, create, update, delete, stop, deployment_*, freeze_*

Búsqueda y análisis

Meta-herramienta	Descripción	Acciones principales
gitlab_search	Búsqueda entre recursos en proyectos, grupos y ámbito global	code, issues, merge_requests, commits, milestones, notes, projects, snippets, users, wiki
gitlab_analyze	Análisis con sampling de IA (11 operaciones vía sampling de LLM)	analyze_mr_changes, summarize_issue, pipeline_failure, …

Acceso y credenciales

Meta-herramienta	Descripción	Acciones principales
gitlab_access	Deploy keys, deploy tokens, tokens de acceso de proyecto, tokens de acceso de grupo y solicitudes de acceso	deploy_key_*, deploy_token_*, project_token_*, group_token_*
gitlab_admin	Administración de instancia: Sidekiq, ajustes, licencia, mensajes broadcast, hooks, PATs y más	sidekiq_*, setting_*, license_*, broadcast_*, hook_*, pat_*

Paquetes y contenido

Meta-herramienta	Descripción	Acciones principales
gitlab_package	Gestión del registro de paquetes y subida/descarga de archivos genéricos	list, get, delete, upload, download, protection_rule_*
gitlab_snippet	Snippets de proyecto y personales con discusiones, notas y award emoji	list, get, create, update, delete, discussion_*, note_*
gitlab_template	Plantillas de proyecto (gitignores, CI YAML, Dockerfiles, licencias) y CI lint	gitignore_*, ci_*, dockerfile_*, license_*, lint

Descubrimiento y utilidades

Meta-herramienta	Descripción	Acciones principales
gitlab_feature_flags	Gestión de feature flags y listas de usuarios de feature flags	list, get, create, update, delete, user_list_*
gitlab_model_registry	Descarga de archivos de modelos ML del Model Registry de GitLab	download
gitlab_ci_catalog	Descubrimiento de recursos del CI/CD Catalog (componentes, plantillas)	list, get
gitlab_custom_emoji	Gestión de emojis personalizados a nivel de grupo vía GraphQL	list, get, create, delete
gitlab_resolve_project	Resolución de URLs remotas Git a IDs de proyecto GitLab	resolve

Nota

Dos herramientas standalone adicionales (gitlab_server_check_update, gitlab_server_apply_update) se registran en los modos meta e individual cuando la autoactualización está habilitada. El modo dinámico expone las mismas acciones de actualización mediante el catálogo canónico de acciones.

Herramientas solo Enterprise

Cuando el catálogo Enterprise/Premium está habilitado, el servidor registra 15 meta-herramientas adicionales para funciones Premium y Ultimate en instancias autoalojadas:

gitlab_merge_train, gitlab_audit_event, gitlab_dora_metrics, gitlab_dependency, gitlab_external_status_check, gitlab_group_scim, gitlab_member_role, gitlab_enterprise_user, gitlab_attestation, gitlab_compliance_policy, gitlab_project_alias, gitlab_geo, gitlab_storage_move, gitlab_vulnerability, gitlab_security_finding

En GitLab.com Enterprise/Premium, el catálogo también registra gitlab_orbit con cinco acciones de solo lectura del Knowledge Graph: status, schema, tools, query y graph_status.

Nota

Las herramientas Enterprise requieren una licencia de GitLab Premium o Ultimate en tu instancia. Forzar el catálogo Enterprise/Premium en una instancia Community Edition registrará las herramientas, pero las llamadas a la API devolverán errores de permisos.

Lectura adicional

• 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 Enterprise/Premium
• Herramientas de análisis — herramientas de sampling impulsadas por IA
• Recursos y prompts — contexto de solo lectura y plantillas de prompts