Glossary

These are the terms this documentation uses that are specific to GitLab MCP Server or to the Model Context Protocol. Each definition stands on its own, so you can read just the one you need.

A tool surface is the set of MCP tools a client actually sees at startup. GitLab MCP Server has three, selected with TOOL_SURFACE:

Surface	Visible tools	Selected with
Dynamic (default)	2	TOOL_SURFACE=dynamic, or leave unset
Meta-tool	32 domain tools (more with Enterprise)	TOOL_SURFACE=meta
Individual	847–1071	TOOL_SURFACE=individual

All three are projections of the same action catalog, so they differ in packaging and token cost, never in capability. See tools overview.

The canonical action catalog is the single internal definition of every GitLab operation the server exposes. Each entry carries its route, input and output schema, destructive classification, and licensing tier. Every visible tool surface is generated from this catalog, which is why behaviour and safety are identical no matter which surface a client uses.

A canonical action ID identifies one operation, written domain.action — for example issue.list or merge_request.approve. Dynamic mode returns these from gitlab_find_action and executes them through gitlab_execute_action.

A meta-tool is a domain-level MCP tool that groups related operations behind a single tool with an action parameter. gitlab_issue, for instance, handles list, get, create, update and delete. Meta-tools cut the visible tool count by more than 95% while keeping every operation reachable as an action. See meta-tools.

Dynamic mode is the default tool surface, exposing only gitlab_find_action and gitlab_execute_action. The assistant searches the catalog for the operation it needs, receives that action’s exact schema, then executes it. This costs one discovery call per task and keeps startup context about 444× smaller than registering every tool individually. See dynamic toolset.

Tier gating registers only the actions and schema fields the connected GitLab licence supports. The tier comes from GITLAB_TIER when set, otherwise it is detected from the instance licence, falling back to Free. Input schemas are pruned strictly, so a lower tier never sees higher-tier fields; output schemas are pruned leniently, so data still reaches the client.

Safe mode (GITLAB_SAFE_MODE=true) intercepts every mutating tool call and returns a JSON preview of what would happen, instead of performing it. It is distinct from read-only mode, which removes the operations altogether rather than previewing them.

Read-only mode (GITLAB_READ_ONLY=true) omits every mutating action from the registered catalog. The assistant cannot call a write operation because no such tool exists in its list — a stronger guarantee than declining the call at execution time.

Elicitation is an MCP capability that lets the server ask the user for input through a structured form mid-conversation, instead of requiring every parameter up front. GitLab MCP Server uses it for interactive creation flows, and falls back to standard parameterised tools on clients that do not support it. See elicitation.

The capability surface decides which MCP resources and prompts are registered, selected with CAPABILITY_SURFACE. full registers all of them; minimal registers only the gitlab://tools manifest, cutting shared startup context from roughly 31,800 tokens to about 1,100 while keeping per-action schema discovery available.

The tool manifest resources are gitlab://tools and gitlab://tools/{id}. The first lists every visible tool and executable action for the active surface; the second returns the accepted call shape and JSON Schema for one action. Both stay available under a minimal capability surface, which is how a client discovers exact parameters without inflating the tool list.

A destructive action is one the catalog classifies as irreversible or data-losing — deleting a project, erasing job artifacts. These require explicit confirmation before executing, and dynamic mode additionally suppresses weak fuzzy-match results for them, so a typo cannot select one.

stdio transport is the default: the AI client spawns the server as a child process and exchanges JSON-RPC over stdin and stdout. The token is supplied as an environment variable, never leaves the local machine, and there is no network exposure.

HTTP transport is the multi-user mode: one process serves many clients over the network, each authenticating with its own GitLab token. Sessions are isolated in a bounded LRU pool keyed by a hash of token and GitLab URL, so no state is shared between clients. See HTTP server mode.

Tool schema tokens are the token cost of the visible tool definitions a client receives on every tools/list — input schemas, annotations and descriptions. This is the figure that distinguishes the tool surfaces from one another. It is measured with the {footprint.tokenizer} tokenizer and excludes MCP resources and prompts, which are counted separately as shared tokens.