Tools Overview

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. All three reach the same GitLab API surface. They differ only in packaging, so the choice trades context cost against tool-list granularity — never capability.

Every mode is projected from one canonical action catalog. That gives all three identical handlers, typed schemas, and safety behavior. Only the presentation changes. Dynamic mode searches and executes canonical domain.action IDs. Meta-tool mode groups actions by domain. Individual mode registers one tool per operation.

Which tool mode should I use?

Dynamic mode is the default, and the right choice for most assistants. It keeps two tools in the model’s context and still reaches every GitLab operation. Choose meta-tool mode when your client works better with a fixed, domain-level tool list. Choose 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.

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

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.

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, 1,065 on self-managed Enterprise/Premium, and 1,071 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.

What are the three tool modes in GitLab MCP Server?

GitLab MCP Server offers three tool modes that expose the same GitLab API surface with different packaging. Dynamic mode (the default) exposes two public tools that search and execute a canonical action catalog. Meta-tool mode groups related operations into domain-level tools that route on an action parameter. Individual mode registers one MCP tool per GitLab operation. All three modes share identical handlers, schemas, and safety behavior.

Which tool mode is the most token-efficient?

Dynamic mode is the most token-efficient because it exposes only two public tools regardless of how many GitLab operations exist. The assistant first calls gitlab_find_action to retrieve an action and its schema, then calls gitlab_execute_action. This keeps the tool list small in the model's context window while still reaching every GitLab operation through the shared action catalog.

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

Source reference

Maintained by José Manuel Requena PlensGitHub LinkedIn Mastodon Google Scholar All projects