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.

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.

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

Individual mode registers one MCP tool per GitLab operation: 866 tools for CE, 1085 tools for self-managed Enterprise/Premium, or 1091 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.

What it exposes

one visible MCP tool per GitLab operation, each with its own typed input and output schema — the whole catalog, flat.

Requires

GITLAB_MCP_TOOL_SURFACE=individual, and a client with the context budget to hold the full tool list.

Tier effect

the tool count itself moves with the licence: Free/CE registers the base catalog, Premium and Ultimate add their gated tools, and lower tiers never see higher-tier input fields in the schemas.

What it does not do

low-token startup: listing every tool is the point of this surface, so the discovery cost cannot be reduced without changing surface. Clients with small context windows should use the dynamic default instead.

Meta-tool mode (GITLAB_MCP_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 34 base meta-tools, 51 on self-managed Enterprise/Premium, or 52 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",
    "params": {
      "project_id": "my-group/my-project",
      "title": "Fix login redirect",
      "description": "Users are redirected to 404 after login",
      "labels": ["bug", "priority::high"]
    }
  }
}

What it exposes

one dispatcher tool per domain (projects, issues, merge requests, pipelines…), each routing an action parameter to the same handlers the other surfaces use.

Requires

GITLAB_MCP_TOOL_SURFACE=meta. Per-action call shapes stay discoverable through gitlab://tools and gitlab://tools/{id} whatever GITLAB_MCP_META_PARAM_SCHEMA is set to.

Tier effect

Premium/Ultimate add dedicated enterprise meta-tools and inject enterprise-only routes into gitlab_project, gitlab_group and gitlab_issue.

What it does not do

per-operation tool descriptions in the client’s tool list: a dispatcher summarises its domain, so an assistant that needs an exact schema reads it from the catalog resources rather than from tools/list.

Dynamic mode (GITLAB_MCP_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 all three modes share the canonical action catalog, safety behavior stays consistent across every surface: read-only filtering, safe-mode previews, token-scope filtering, destructive-action confirmations, schemas, and result formatting are identical.

What it exposes

two tools — gitlab_find_action and gitlab_execute_action — reaching the full canonical catalog: find returns exact schemas, execute runs the canonical domain.action.

Requires

nothing: it is the default when GITLAB_MCP_TOOL_SURFACE is unset. GITLAB_MCP_CAPABILITY_SURFACE=minimal shrinks the shared resource/prompt footprint further.

Tier effect

invisible in tools/list (always two tools) but real in reach: find only surfaces, and execute only accepts, the actions the resolved tier registers.

What it does not do

a browsable tool list: the client sees two tools, so a human scanning tools/list learns nothing about coverage — that is what gitlab://tools and the find tool are for.

All tools follow a consistent naming pattern:

• Individual tools: the prevailing form is gitlab_{domain}_{action} (e.g., gitlab_issue_create, gitlab_project_list), domain first; a legacy set is verb first instead (gitlab_list_issue_discussions, gitlab_add_ssh_key), and each name is declared in the action’s catalog spec rather than derived, so read it from gitlab://tools instead of inferring it
• 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)

Five more tools are registered alongside the dispatchers. They take their parameters directly, with no action envelope, and keep the same names in individual mode:

When the resolved tier is Premium or Ultimate, the server registers up to 17 additional self-managed meta-tools for GitLab Premium and Ultimate features. Six arrive with Premium:

gitlab_audit_event, gitlab_enterprise_user, gitlab_geo, gitlab_group_scim, gitlab_merge_train, gitlab_project_alias

Eleven more arrive with Ultimate:

gitlab_attestation, gitlab_compliance_policy, gitlab_dependency, gitlab_dora_metrics, gitlab_external_status_check, gitlab_member_role, gitlab_security_attribute, gitlab_security_category, gitlab_security_finding, gitlab_security_scan_profile, gitlab_vulnerability

On GitLab.com with a Premium or Ultimate tier, 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 34 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 866 tools on CE, 1,085 on self-managed Enterprise/Premium, and 1,091 on GitLab.com when Orbit is available. Meta-tool mode exposes 34 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.

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

• 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