Tools Overview

Developer Documentation

This page is the user-facing overview. For the full per-domain tool reference, see docs/reference/tools.

GitLab MCP Server exposes GitLab operations as MCP tools that AI assistants can invoke directly. It offers three tool modes — dynamic, meta-tool, and individual — that expose the same GitLab API surface with different packaging, so you can trade LLM context cost for tool-list granularity without losing any capability.

All three modes are projected from one canonical action catalog, so they share identical handlers, typed schemas, and safety behavior. They differ only in how operations are presented to the assistant: dynamic mode searches and executes canonical domain.action IDs, meta-tool mode groups actions by domain, and individual mode registers one tool per operation.

Which tool mode should I use?

Choose the mode that matches how your MCP client discovers tools and how much context budget you can spend on the tool list. Dynamic mode is the default and the right choice for most assistants, because it keeps only two tools in the model’s context while still reaching every GitLab operation. Step up to meta-tool mode when your client works better with a fixed, domain-level tool list, and use individual mode only when a client needs every operation enumerated up front.

Mode	Public tools exposed	Best for	Relative token cost
Dynamic (default)	2 — gitlab_find_action, gitlab_execute_action	Most assistants; lowest context overhead	Lowest
Meta-tool	32 base domain tools (more with Enterprise)	A fixed, discoverable, domain-level tool list	Medium
Individual	847–1071 tools	Clients that need every operation pre-listed	Highest

Set the mode with the TOOL_SURFACE environment variable (dynamic, meta, or individual). Dynamic mode is used when TOOL_SURFACE is unset.

Operating modes

How does individual mode work?

Individual mode registers one MCP tool per GitLab operation: 847 tools for CE, 1065 tools for self-managed Enterprise/Premium, or 1071 tools on GitLab.com Enterprise/Premium when Orbit is available. This gives an AI assistant maximum granularity — every operation is a distinct, individually described tool — at the cost of significant context tokens spent listing and disambiguating tools during discovery.

How does meta-tool mode work?

Meta-tool mode (TOOL_SURFACE=meta) consolidates related operations into domain-level meta-tools. Each meta-tool accepts an action parameter that routes to the appropriate handler, reducing the tool count to 32 base meta-tools, 49 on self-managed Enterprise/Premium, or 50 on GitLab.com Enterprise/Premium when Orbit is available. This dramatically improves token efficiency over individual mode while keeping a fixed, browsable tool list.

{
  "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"
  }
}

How does the dynamic toolset work?

Dynamic mode (TOOL_SURFACE=dynamic) is the low-token default. It exposes only two public tools — gitlab_find_action and gitlab_execute_action (the singular gitlab_execute_action name is intentional) — while keeping every GitLab action reachable through the canonical catalog. The assistant first finds an action and its exact schema, then executes the canonical domain.action ID.

flowchart LR
	A[Find action and schema] --> B[Execute domain.action]
	B --> C[Existing GitLab handler]

Because meta-tools and dynamic mode share the canonical action catalog, safety behavior stays consistent across both modes: read-only filtering, safe-mode previews, token-scope filtering, destructive-action confirmations, schemas, and result formatting are identical.

Tool naming convention

All tools follow a consistent naming pattern:

• Individual tools: gitlab_{action}_{resource} (e.g., gitlab_create_issue, gitlab_list_projects)
• Meta-tools: gitlab_{domain} (e.g., gitlab_issue, gitlab_project)
• Dynamic actions: canonical domain.action IDs executed through gitlab_execute_action (e.g., issue.create, merge_request.list)

Base meta-tools (32)

Project management

Meta-tool	Description	Key Actions
gitlab_project	Project CRUD, configuration, hooks, labels, milestones, members, badges, access tokens, todo, upload, and more	list, get, create, update, delete, fork, star, archive, label_*, milestone_*, members, badge_*, upload
gitlab_issue	Issue lifecycle, notes, discussions, links, work items (including work item types), time tracking, award emoji, and resource events	list, get, create, update, delete, note_*, link_*, discussion_*, work_item_*, time_*
gitlab_group	Group CRUD, subgroups, members, badges, hooks, labels, milestones, transfer, and descendant projects	list, get, create, update, delete, label_*, milestone_*, member_*, badge_*, hook_*
gitlab_user	User information, status, SSH keys, GPG keys, emails, activity, preferences, and instance service accounts (Enterprise)	get, current, list, ssh_key_*, gpg_key_*, email_*, status_*, service_account_*
gitlab_wiki	Wiki page management and attachments	list, get, create, update, delete, upload_attachment

Code & repository

Meta-tool	Description	Key Actions
gitlab_branch	Branch management and protection rules (including branch rule queries via GraphQL)	list, get, create, delete, protect, unprotect, branch_rule_*
gitlab_tag	Tag management and protection rules with GPG signature verification	list, get, create, delete, protect, unprotect
gitlab_release	Release management and release asset links	list, get, create, update, delete, link_*
gitlab_repository	Repository tree, files, commits, diffs, blame, compare (including cross-project), cherry-pick, revert, contributors, archives, changelogs, markdown	tree, file_*, commit_*, compare, blame, archive, changelog, submodule_*, discussion_*
gitlab_merge_request	MR lifecycle, approvals, approval rules, time tracking, subscriptions, context commits, award emoji, and resource events	list, get, create, update, merge, rebase, approve, approval_*, time_*, event_*

Code review

Meta-tool	Description	Key Actions
gitlab_mr_review	MR notes, threaded discussions, code diffs, draft notes, and diff versions	note_*, discussion_*, diff_*, draft_*, version_*

CI/CD

Meta-tool	Description	Key Actions
gitlab_pipeline	Pipeline management, resource groups, test reports, trigger tokens, pipeline bridges, and pipeline schedules	list, get, create, cancel, retry, delete, wait, schedule_*, trigger_*
gitlab_job	CI job management, artifacts, logs, and Kubernetes agents (force cancel supported)	list, get, play, cancel, retry, erase, trace, artifacts, wait, k8s_*
gitlab_runner	CI/CD runner management, runner controllers, controller scopes, and controller tokens	list, get, update, remove, jobs, controller_*, register, verify
gitlab_ci_variable	CI/CD variables at instance, group, and project scope	list, get, create, update, delete (at each scope level)
gitlab_environment	Environment management, protected environments, deployment freeze periods, and deployment records	list, get, create, update, delete, stop, deployment_*, freeze_*

Search & analysis

Meta-tool	Description	Key Actions
gitlab_search	Cross-resource search across projects, groups, and global scope	code, issues, merge_requests, commits, milestones, notes, projects, snippets, users, wiki

Access & credentials

Meta-tool	Description	Key Actions
gitlab_access	Deploy keys, deploy tokens, project access tokens, group access tokens, and access requests	deploy_key_*, deploy_token_*, project_token_*, group_token_*
gitlab_admin	Instance administration: Sidekiq, settings, license, broadcast messages, hooks, PATs, and more	sidekiq_*, setting_*, license_*, broadcast_*, hook_*, pat_*

Packages & content

Meta-tool	Description	Key Actions
gitlab_package	Package registry management and generic package file upload/download	list, get, delete, upload, download, protection_rule_*
gitlab_snippet	Project and personal snippets with discussions, notes, and award emoji	list, get, create, update, delete, discussion_*, note_*
gitlab_template	Project templates (gitignores, CI YAML, Dockerfiles, licenses) and CI linting	gitignore_*, ci_*, dockerfile_*, license_*, lint

Discovery & utilities

Meta-tool	Description	Key Actions
gitlab_feature_flags	Feature flag and feature flag user list management	list, get, create, update, delete, user_list_*
gitlab_model_registry	ML model package file download from GitLab Model Registry	download
gitlab_ci_catalog	CI/CD Catalog resource discovery (reusable components, templates)	list, get
gitlab_custom_emoji	Group-level custom emoji management via GraphQL	list, get, create, delete
gitlab_resolve_project	Resolve Git remote URLs to GitLab project IDs	resolve

Note

Two additional standalone tools (gitlab_server_check_update, gitlab_server_apply_update) are registered in meta and individual modes when auto-update is enabled. Dynamic mode exposes the same update actions through the canonical action catalog.

Enterprise-only tools

When the Enterprise/Premium catalog is enabled, the server registers 16 additional self-managed meta-tools for GitLab Premium and Ultimate features:

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_vulnerability, gitlab_security_attribute, gitlab_security_category, gitlab_security_finding

On GitLab.com Enterprise/Premium, the catalog also registers gitlab_orbit with six read-only Knowledge Graph actions: status, schema, tools, dsl, query, and graph_status.

Note

Enterprise tools require a GitLab Premium or Ultimate license on your instance. Forcing the Enterprise/Premium catalog on a Community Edition instance will register the tools but API calls will return permission errors.

Frequently asked questions

What is the difference between meta-tool mode and dynamic mode?

Both meta-tool and dynamic mode reduce token cost compared with individual mode, but they package operations differently. Meta-tool mode exposes a fixed list of 32 domain-level tools, each routing on an action parameter — useful when a client works best with a stable, browsable tool list. Dynamic mode exposes only two tools and resolves operations on demand through search, giving the smallest possible tool list. Both share the same handlers and safety behavior.

Do all modes support the same GitLab operations?

Yes. Dynamic, meta-tool, and individual modes are all projected from one canonical action catalog, so they cover the same GitLab REST and GraphQL operations. They differ only in packaging, not capability. Read-only filtering, safe-mode previews, destructive-action confirmations, token-scope filtering, and result formatting behave identically regardless of the mode you choose.

How many tools does each mode expose?

Individual mode exposes 847 tools on CE, 1065 on self-managed Enterprise/Premium, and 1071 on GitLab.com when Orbit is available. Meta-tool mode exposes 32 base domain tools (more with the Enterprise catalog). Dynamic mode always exposes exactly two public tools, regardless of how many GitLab operations are available.

Do Enterprise tools require a paid GitLab license?

Yes. Enterprise meta-tools — such as merge trains, DORA metrics, vulnerabilities, and compliance policies — require a GitLab Premium or Ultimate license on the connected instance. Forcing the Enterprise catalog on a Community Edition instance registers the tools, but the underlying API calls return permission errors because the features are not licensed.

Further reading

• Meta-tools — detailed meta-tool architecture and usage
• Dynamic toolset — low-token search/describe/execute mode
• Orbit — GitLab.com Enterprise/Premium Knowledge Graph tools
• Resources & Prompts — read-only context and prompt templates

External references

• Model Context Protocol specification — the protocol these tools implement
• GitLab REST API v4 — the REST surface most tools call
• GitLab GraphQL API — the GraphQL surface used by the remaining domains