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 rules, apart from how a destructive call is confirmed. Otherwise 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: 868 tools on Free/CE, 1022 tools on self-managed Premium, 1088 tools on self-managed Ultimate, or 1094 tools on GitLab.com Ultimate, where 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.

Each tool requires exactly the parameters its action requires on the meta-tool and dynamic surfaces, which follow what GitLab requires of the request the action sends, apart from a few the server fills in itself, keeps required so it never sends a null in place of a value, or asks for as a choice of two, such as a member named by user_id or username. A parameter GitLab fills in when it is left out, such as the link_type of an issue link, is optional in every mode, and one GitLab cannot do without, such as the commit sha of a cherry-pick, is required in every mode.

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 meta-tools on Free/CE, 40 on self-managed Premium, 51 on self-managed Ultimate, or 52 on GitLab.com Ultimate, where 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 give seven base dispatchers more actions: gitlab_project, gitlab_group, gitlab_issue, gitlab_merge_request, gitlab_environment, gitlab_storage_move and gitlab_runner.

What it does not do

each action’s exact parameter schema in tools/list under the default opaque mode: a dispatcher’s description carries a line of guidance per action, and an assistant reads the exact schema from the catalog resources (gitlab://tools/{id}) unless GITLAB_MCP_META_PARAM_SCHEMA is compact or full.

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, the safety rules come from one place: read-only filtering, safe mode, token-scope filtering, the destructive classification, schemas, and result formatting are the same on every surface. How a destructive call is confirmed differs in one way: the dynamic surface never prompts, so it needs confirm: true on every one unless GITLAB_MCP_YOLO_MODE skips the confirmation, as it does on every surface, which Destructive actions explains.

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)

The 34 tools a Free/CE instance serves are 28 domain dispatchers, the gitlab_server diagnostics tool and five tools that take their arguments directly. Premium and Ultimate add actions to seven of these dispatchers; the number of actions each one has on each tier is in Meta-tools.

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, for 40 meta-tools (the action count of each is in parentheses):

gitlab_audit_event (6), gitlab_enterprise_user (4, needs admin_mode), gitlab_geo (8, needs admin_mode), gitlab_group_scim (4), gitlab_merge_train (4), gitlab_project_alias (4, needs admin_mode)

Eleven more arrive with Ultimate, for 51 on a self-managed instance:

gitlab_attestation (2), gitlab_compliance_policy (2), gitlab_dependency (4), gitlab_dora_metrics (2), gitlab_external_status_check (8), gitlab_member_role (6), gitlab_security_attribute (5), gitlab_security_category (3), gitlab_security_finding (1), gitlab_security_scan_profile (3), gitlab_vulnerability (8)

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. That makes 52 meta-tools on GitLab.com Ultimate.

A group that needs admin_mode is left out for a token without that scope (Scope-based tool filtering). What the two tiers add to the base dispatchers is listed under Enterprise mode.

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 tools (34 on Free/CE, up to 52 on GitLab.com Ultimate), most of them domain-level tools 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 rules, apart from how a destructive call is confirmed.

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 in packaging, not capability. Read-only filtering, safe mode, the destructive classification, token-scope filtering, and result formatting are shared by every mode. How a destructive call is confirmed is the one difference: the default dynamic surface never prompts, so it needs confirm: true on every one unless GITLAB_MCP_YOLO_MODE skips the confirmation, as it does on every surface.

How many tools does each mode expose?

Individual mode exposes 868 tools on Free/CE, 1,022 on self-managed Premium, 1,088 on self-managed Ultimate and 1,094 on GitLab.com Ultimate, where Orbit is available. Meta-tool mode exposes 34 tools on Free/CE, 40 on self-managed Premium, 51 on self-managed Ultimate and 52 on GitLab.com Ultimate. 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 fail: Community Edition does not serve those endpoints and answers 404, and an unlicensed Enterprise Edition refuses them.

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, typed schemas, and safety rules, apart from how a destructive call is confirmed.

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.

• Tools by domain: every action of every catalog group, with its parameters and the tier it needs
• Meta-tools — detailed meta-tool architecture and usage
• Dynamic toolset: the low-token find and execute mode
• Orbit — GitLab.com Premium/Ultimate Knowledge Graph tools
• Resources & Prompts — read-only context and prompt templates
• Output format: what a tool result carries, in Markdown and in JSON
• Command line and environment variables: every setting that picks a surface, a tier or a filter

• 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