Feature flags

Feature flags a project’s application reads to switch a feature on gradually: each flag carries strategies (all users, a percentage of users or of rollout, chosen user IDs or a user list), scoped to environments. These actions manage the flags and the user lists a strategy can target. Turning a flag inactive keeps its history; deleting it does not. The instance’s own GitLab feature flags are administration actions instead (see Administration).

Sample questions

• “List the feature flags of project 42”
• “Roll new-checkout out to 25 percent of users in production”
• “Create a user list for the beta testers”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as feature_flags.feature_flag_create, and its parameters in params. gitlab_find_action finds an ID from a description of the task.
• Meta (GITLAB_MCP_TOOL_SURFACE=meta): call gitlab_feature_flags with action set to the action’s name, such as feature_flag_create, and its parameters in params.
• Individual (GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such as gitlab_feature_flag_create, with its parameters as the arguments.

Availability

Every tier serves the whole group, on self-managed instances and on GitLab.com alike.

Read-only actions: 4 of 10, the ones a deployment in read-only mode keeps. A token with read_api and not api is served 4 of the 10.

Actions

The description of each action, and of each of its parameters, is the text the server serves for it on the default surface, quoted as served. The token lines say what GitLab 19.4.1 requires of a token for the requests each action sends; on an instance with Admin Mode turned on, an action only an administrator may run also needs admin_mode. A destructive action runs only once confirmed, unless GITLAB_MCP_YOLO_MODE (or AUTOPILOT) skips that step: the dynamic surface needs confirm: true on gitlab_execute_action, and the other two take a confirm parameter or the client’s prompt (Destructive actions).

Action	Individual
feature_flags.feature_flag_create	gitlab_feature_flag_create
feature_flags.feature_flag_delete	gitlab_feature_flag_delete
feature_flags.feature_flag_get	gitlab_feature_flag_get
feature_flags.feature_flag_list	gitlab_feature_flag_list
feature_flags.feature_flag_update	gitlab_feature_flag_update
feature_flags.ff_user_list_create	gitlab_ff_user_list_create
feature_flags.ff_user_list_delete	gitlab_ff_user_list_delete
feature_flags.ff_user_list_get	gitlab_ff_user_list_get
feature_flags.ff_user_list_list	gitlab_ff_user_list_list
feature_flags.ff_user_list_update	gitlab_ff_user_list_update

feature_flags.feature_flag_create

Create a feature flag with optional activation strategies and scopes. Returns: the created flag with active state, version, scopes, and strategies. See also: feature_flags.feature_flag_get, feature_flags.feature_flag_update.

• Meta-tool: gitlab_feature_flags, action feature_flag_create
• Individual tool: gitlab_feature_flag_create
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Feature Flag: Create at project (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
name	string	yes	Feature flag name
project_id	string/integer	yes	Project ID or path
active	boolean	no	Whether the flag is active
description	string	no	Feature flag description
strategies	object[]	no	Activation strategies for the flag. Each has a name, optional parameters, and optional environment scopes
version	string	no	Version of the feature flag (new_version_flag)

feature_flags.feature_flag_delete

Delete a feature flag permanently. Returns: a success confirmation naming the flag. See also: feature_flags.feature_flag_get, feature_flags.feature_flag_list.

• Meta-tool: gitlab_feature_flags, action feature_flag_delete
• Individual tool: gitlab_feature_flag_delete
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Feature Flag: Delete at project (permissions page)
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
name	string	yes	Feature flag name
project_id	string/integer	yes	Project ID or path

feature_flags.feature_flag_get

Get a single feature flag by name. Returns: the flag with active state, version, environment scopes, and activation strategies. See also: feature_flags.feature_flag_list, feature_flags.feature_flag_update, feature_flags.feature_flag_delete.

• Meta-tool: gitlab_feature_flags, action feature_flag_get
• Individual tool: gitlab_feature_flag_get
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Feature Flag: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
name	string	yes	Feature flag name
project_id	string/integer	yes	Project ID or path

feature_flags.feature_flag_list

List feature flags in a project with optional scope filter, ordering, and pagination. Returns: matching feature flags with active state, version, scopes, strategies, and pagination metadata. See also: feature_flags.feature_flag_get, feature_flags.feature_flag_create.

• Meta-tool: gitlab_feature_flags, action feature_flag_list
• Individual tool: gitlab_feature_flag_list
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Feature Flag: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or path
order_by	string	no	Column to order results by (e.g. name, created_at, updated_at)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
scope	string (enabled, disabled)	no	Filter by scope (enabled or disabled)
sort	string (asc, desc)	no	Sort direction (asc, desc)

feature_flags.feature_flag_update

Update a feature flag’s name, description, active state, or strategies. Returns: the updated flag with active state, version, scopes, and strategies. See also: feature_flags.feature_flag_get, feature_flags.feature_flag_delete.

• Meta-tool: gitlab_feature_flags, action feature_flag_update
• Individual tool: gitlab_feature_flag_update
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Feature Flag: Update at project (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
name	string	yes	Current feature flag name
project_id	string/integer	yes	Project ID or path
active	boolean	no	Whether the flag is active
description	string	no	Feature flag description. Pass an empty string to remove it. Omit the field to leave it untouched
new_name	string	no	New feature flag name
strategies	object[]	no	Activation strategies for the flag. Each has an optional id (to update an existing strategy), a name, optional parameters, and optional environment scopes carrying their own id and _destroy

feature_flags.ff_user_list_create

Create a feature flag user list in a project. Returns: the created list with id, iid, project_id, name, user_xids, created_at, and updated_at. See also: feature_flags.ff_user_list_list, feature_flags.ff_user_list_get, feature_flags.ff_user_list_update.

• Meta-tool: gitlab_feature_flags, action ff_user_list_create
• Individual tool: gitlab_ff_user_list_create
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Feature Flag User List: Create at project (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
name	string	yes	User list name
project_id	string/integer	yes	Project ID or path
user_xids	string	yes	Comma-separated list of user external IDs

feature_flags.ff_user_list_delete

Delete a feature flag user list by its user_list_iid. Returns: a success confirmation naming the deleted list. See also: feature_flags.ff_user_list_get, feature_flags.ff_user_list_list.

• Meta-tool: gitlab_feature_flags, action ff_user_list_delete
• Individual tool: gitlab_ff_user_list_delete
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Feature Flag User List: Delete at project (permissions page)
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or path
user_list_iid	integer	yes	Feature flag user list internal ID returned by list or create. Do not use the user list name

feature_flags.ff_user_list_get

Get a single feature flag user list by its user_list_iid. Returns: the list’s id, iid, project_id, name, user_xids, created_at, and updated_at. See also: feature_flags.ff_user_list_list, feature_flags.ff_user_list_update, feature_flags.ff_user_list_delete.

• Meta-tool: gitlab_feature_flags, action ff_user_list_get
• Individual tool: gitlab_ff_user_list_get
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Feature Flag User List: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or path
user_list_iid	integer	yes	Feature flag user list internal ID returned by list or create. Do not use the user list name

feature_flags.ff_user_list_list

List feature flag user lists for a project with search, ordering, and offset or keyset pagination. Returns: each list’s id, iid, project_id, name, user_xids, created_at, updated_at, plus pagination metadata. See also: feature_flags.ff_user_list_get, feature_flags.ff_user_list_create.

• Meta-tool: gitlab_feature_flags, action ff_user_list_list
• Individual tool: gitlab_ff_user_list_list
• Tier: Free
• Classic or OAuth token: read_api (or api)
• Fine-grained token: Feature Flag User List: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or path
order_by	string	no	Order results by field (e.g. created_at, updated_at, name)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
search	string	no	Search by name
sort	string (asc, desc)	no	Sort direction (asc, desc)

feature_flags.ff_user_list_update

Update a feature flag user list’s name or user_xids by its user_list_iid. Returns: the updated list with id, iid, project_id, name, user_xids, created_at, and updated_at. See also: feature_flags.ff_user_list_get, feature_flags.ff_user_list_list, feature_flags.ff_user_list_delete.

• Meta-tool: gitlab_feature_flags, action ff_user_list_update
• Individual tool: gitlab_ff_user_list_update
• Tier: Free
• Classic or OAuth token: api
• Fine-grained token: Feature Flag User List: Update at project (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or path
user_list_iid	integer	yes	Feature flag user list internal ID returned by list or create. Do not use the user list name
name	string	no	New user list name
user_xids	string	no	Comma-separated list of user external IDs