:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
# MCP tool definitions. Tools are opt-in: an operation is exposed only when it has an entry here.
# List operations without an entry: pnpm --filter=@posthog/mcp run scaffold-yaml -- --candidates --product feature_flags
# Add one: pnpm --filter=@posthog/mcp run scaffold-yaml -- --add <operationId> --product feature_flags
# To keep an operation off on purpose, set enabled: false and give a disabled_reason.
category: Feature flags
feature: flags
url_prefix: /feature-flags
ui_apps:
feature-flag:
type: detail
view_prop: flag
feature-flag-list:
type: list
detail_tool: feature-flag-get-definition
detail_args: '{ id: item.id }'
item_name_field: key
click_prop: onFlagClick
feature-flag-testing:
type: detail
view_prop: flag
tools:
create-feature-flag:
operation: feature_flags_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: false
enrich_url: '{id}'
title: Create feature flag
description: >
Create a feature flag in the current project. Call when the user asks to add a flag, gate a feature behind a
flag, set up a percentage rollout, or deliver a remote config value. If this flag is for a new version of a
page or flow, or for a pricing or onboarding change, an experiment may be in order. Ask the user if they
want to run an experiment, and if so create the experiment with `experiment-create`, which will manage its
own flag. Release conditions, rollout percentages, multivariate variants, and payloads all go in the
structured `filters` param (`filters.groups` for release conditions, `filters.multivariate.variants` for
variants, `filters.payloads` for JSON-encoded payloads). Use `update-feature-flag` to change an existing
flag. Check the key first: `feature-flag-get-definition-by-key` when you already have the exact key it will
use, `feature-flag-get-all` when you only know part of the key or the name.
include_params:
- key
- name
- filters
- active
- tags
- evaluation_contexts
- is_remote_configuration
- ensure_experience_continuity
- evaluation_runtime
- bucketing_identifier
param_overrides:
is_remote_configuration:
description:
Whether this flag delivers a payload instead of gating a feature (Remote Config mode). When true, set the
delivered payload through the `filters` param under `filters.payloads.true` as a JSON-encoded
string. There is no dedicated payload parameter.
ensure_experience_continuity:
description:
Whether to persist the flag's value for a user across the anonymous-to-identified transition (the "persist
across authentication steps" option in the UI). Keeps a user's evaluated value stable once they log
in. Incompatible with `device_id` bucketing.
evaluation_runtime:
description:
Where this flag is allowed to evaluate — `server` (server-side SDKs only), `client` (client-side SDKs
only), or `all` (both). Defaults to `all`.
bucketing_identifier:
description:
Identifier used to bucket users into rollout percentages and variants — `distinct_id` (user ID, the
default) or `device_id`. Using `device_id` is incompatible with `ensure_experience_continuity=true`.
hooks: featureFlags/conditionIdHooks
delete-feature-flag:
operation: feature_flags_partial_update
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: true
idempotent: true
title: Delete feature flag
description: >
Soft-delete a feature flag by ID in the current project.
A flag whose `filters.version` is 2 requires `version`, so read the flag first and send its current
`version`; never guess it. On such a flag a stale `version` returns 409: read the flag again and decide
against its current state. Other flags do not check `version`.
Of the experiments that use the flag, only a running one blocks the delete. Read `experiment_set_metadata`
from `feature-flag-get-definition` first and name every experiment listed there to the user before deleting:
a draft experiment cannot launch until its flag is restored. Use `feature-flag-restore` to undo a delete. A
flag whose `filters.version` is 2 cannot be restored yet, so tell the user before deleting one.
include_params:
- version
inject_body:
deleted: true
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
hooks: featureFlags/conditionIdHooks
feature-flag-archive:
operation: feature_flags_archive_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: true
enrich_url: '{id}'
title: Archive feature flag
description: >
Archive a feature flag, hiding it from the default flag list. Requires the flag's numeric ID; use
`feature-flag-get-definition-by-key` to get it from a key, or `feature-flag-get-all` to search by key or
name.
Sets `archived` to true. An archived flag must be disabled, so an enabled flag is turned off in the same
call. Nothing else changes: this tool never accepts or replaces the `filters` object, and linked experiment
and survey history is preserved. There is no request body.
When the flag is enabled, archiving stops it evaluating everywhere. Tell the user what else this affects:
linked experiments, surveys, early access features and session replay settings all appear in the flag's full
definition.
Returns 400 when the flag is enabled and other active flags depend on it. Returns 409 when an approval
policy gates disabling. Archiving an already-archived flag succeeds and changes nothing, so retrying is
safe.
`feature-flag-get-definition-by-key` also finds archived flags, so a flag that is already archived is
returned with `archived: true` rather than looking missing on a retry. `feature-flag-get-all` hides archived
flags unless you pass `{"archived":"true"}`.
Use `feature-flag-unarchive` to put the flag back in the list, or `delete-feature-flag` when the user wants
it gone rather than tidied away.
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
response:
include:
- id
- key
- active
- archived
- status
- version
feature-flag-disable:
operation: feature_flags_disable_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: true
enrich_url: '{id}'
title: Disable feature flag
description: >
Turn a feature flag off. Requires the flag's numeric ID; use `feature-flag-get-definition-by-key` to get it
from a key, or `feature-flag-get-all` to search by key or name.
Sets `active` to false and changes nothing else. This tool never accepts or replaces the `filters` object,
so targeting, rollout percentages, variants and payloads cannot change.
Pass `version` from the flag you read. A flag whose `filters.version` is 2 requires it, so read the flag
first and send its current `version`; never guess it. When the call would change the flag, a stale `version`
returns 409: read the flag again and decide against its current state. A call that changes nothing succeeds
without checking `version`, and the response carries the current `version`.
A disabled flag stops evaluating everywhere, so every caller falls back to its own default. Tell the user
what else this affects: linked experiments, surveys, early access features and session replay settings all
appear in the flag's full definition. `feature-flag-get-definition-by-key` already returns it, and
`feature-flag-get-definition` returns it by ID.
Returns 400 when other active flags depend on this one; `feature-flags-dependent-flags-retrieve` lists them.
Returns 409 when an approval policy gates disabling. Disabling an already-disabled flag succeeds and changes
nothing, so retrying is safe.
`feature-flag-get-definition-by-key` also finds archived flags, and an archived flag is already disabled.
`feature-flag-get-all` hides archived flags unless you pass `{"archived":"true"}`.
To turn the flag off at a future time instead, use `scheduled-changes-create` with the `update_status`
operation.
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
response:
include:
- id
- key
- active
- archived
- status
- version
feature-flag-enable:
operation: feature_flags_enable_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: true
enrich_url: '{id}'
title: Enable feature flag
description: >
Turn a feature flag on. Requires the flag's numeric ID; use `feature-flag-get-definition-by-key` to get it
from a key, or `feature-flag-get-all` to search by key or name.
Sets `active` to true and changes nothing else. This tool never accepts or replaces the `filters` object, so
targeting, rollout percentages, variants and payloads cannot change. To change who the flag is served to,
use `update-feature-flag`.
Pass `version` from the flag you read. A flag whose `filters.version` is 2 requires it, so read the flag
first and send its current `version`; never guess it. When the call would change the flag, a stale `version`
returns 409: read the flag again and decide against its current state. A call that changes nothing succeeds
without checking `version`, and the response carries the current `version`.
Returns 400 when the flag is archived (call `feature-flag-unarchive` first), when a flag it depends on is
disabled, or when a release condition targets a deleted cohort (remove that condition with
`update-feature-flag`). Returns 409 when an approval policy gates enabling. Enabling an already-enabled flag
succeeds and changes nothing, so retrying is safe.
`feature-flag-get-definition-by-key` also finds archived flags. `feature-flag-get-all` hides archived flags
unless you pass `{"archived":"true"}`.
To turn the flag on at a future time instead, use `scheduled-changes-create` with the `update_status`
operation.
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
response:
include:
- id
- key
- active
- archived
- status
- version
feature-flag-get-all:
operation: feature_flags_list
enabled: true
scopes:
- feature_flag:read
annotations:
readOnly: true
destructive: false
idempotent: true
enrich_url: '{id}'
list: true
title: Get all feature flags
description: >
Get feature flags in the current project. Supports list filters including search by feature flag key or name
(case-insensitive), then use the returned ID for get/update/delete tools. Pass `active: "STALE"` to list
only stale flags. PostHog calls a flag stale when it is enabled and was last called over 30 days ago, or was
never called, is over 30 days old and is rolled out to everyone. The filter does not return a never-called
flag with an empty `groups` list in `filters`, even when `feature-flags-status-retrieve` calls it stale.
Stale flags are cleanup candidates, not proof that a flag is unused. Disabled flags are not checked for
staleness, so `status: ACTIVE` on a disabled flag is expected. Each row carries `status`, `last_called_at`,
`active` and `created_at`. For the reason behind one flag's status, and its rollout summary, use
`feature-flags-status-retrieve`.
param_overrides:
search:
description:
Search by feature flag key or name (case-insensitive). Use this to find the flag ID for get/update/delete
tools.
active:
description:
Filter by flag state. `"true"` returns enabled flags, `"false"` returns disabled flags, and `"STALE"`
returns enabled flags that PostHog classifies as stale.
limit:
cast: string-int
offset:
cast: string-int
response:
include:
- id
- key
- name
- updated_at
- status
- tags
- last_called_at
- active
- created_at
feature-flag-get-definition:
operation: feature_flags_retrieve
enabled: true
scopes:
- feature_flag:read
annotations:
readOnly: true
destructive: false
idempotent: true
enrich_url: '{id}'
title: Get feature flag definition
description: >
Get a single feature flag's full definition — rollout conditions, variants, payloads, active state — by its
numeric ID. Use `feature-flag-get-definition-by-key` when you only have the string key used in code; use
`feature-flag-get-all` to search by key or name and find the ID.
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
hooks: featureFlags/conditionIdHooks
feature-flag-restore:
operation: feature_flags_partial_update
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: true
enrich_url: '{id}'
title: Restore feature flag
description: >
Restore a soft-deleted feature flag by ID, undoing `delete-feature-flag` or a bulk delete. Requires the
flag's numeric ID. Deleted flags are hidden from `feature-flag-get-all`, so take the ID from the delete
call's response, the experiment that uses the flag, or `system.feature_flags` with `deleted = true` in
`execute-sql`. There, match the key by prefix, because the delete may have renamed it as described below.
Sets `deleted` to false and never accepts or replaces the `filters` object. A flag linked to an experiment
had its key renamed to `<key>:deleted:<id>` when it was deleted. Restoring puts the original key back, or
adds a numeric suffix when another flag has taken that key since, so check the returned `key` and tell the
user if it changed. The flag comes back enabled or disabled, as it was before the delete. A flag that was
archived before the delete stays archived, so check the returned `archived` and call
`feature-flag-unarchive` if the user wants it back in the flag list.
Returns 400 when the flag's `filters.version` is 2: those flags cannot be restored yet. Returns 400 under
`filters` when a release condition targets a cohort that has been deleted: name that condition to the user,
and if they agree, remove it with `update-feature-flag` and retry. Returns 404 when the flag was removed for
good, for example because a new flag took its key after the delete. Restoring a flag that is not deleted
succeeds and leaves it as it was, so retrying is safe.
include_params: []
inject_body:
deleted: false
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
response:
include:
- id
- key
- active
- archived
- deleted
- status
- version
feature-flag-roll-out-to-everyone:
operation: feature_flags_roll_out_to_everyone_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: false
enrich_url: '{id}'
title: Roll feature flag out to everyone
description: >
Serve a feature flag to its whole audience: every user, or every group of the configured type when the flag
aggregates by groups. Requires the flag's numeric ID; use `feature-flag-get-definition-by-key` to get it
from a key, or `feature-flag-get-all` to search by key or name.
Adds a release condition with no property filters at 100% and keeps the existing conditions below it. This
tool never accepts or replaces the `filters` object, so payloads, the holdout and the set of variants cannot
change. On a boolean flag, removing the new condition puts the previous targeting back. On a multivariate
flag the variant distribution is rewritten as well, so removing the condition restores the audience but not
the old split. A flag that already leads with such a condition gains no second one.
This tool changes targeting only. A disabled flag still serves nobody, so check `active` in the response and
use `feature-flag-enable` if it is false. A holdout is evaluated before release conditions, so users in one
keep getting the holdout variant instead of the rollout. Early access enrollment is evaluated before both.
Check `filters.feature_enrollment` in the definition you read. When it is true, this tool refuses the
rollout with 400 and writes nothing. Only the early access feature's own move to general availability with
its roll out to everyone option clears the gate. That move writes the 100% condition itself, so do not call
this tool after it. A plain stage change to general availability leaves `feature_enrollment` true, and this
tool keeps returning 400. The API does not expose that option, so ask the person to make the move in the
early access feature.
`update-feature-flag` and `feature-flag-set-release-condition-rollout` are not gated on enrollment. A
rollout written through either returns 200 while the enrollment marker still decides who is served. Do not
use either tool to bypass the 400.
Check `filters.aggregation_group_type_index` in the definition you read. When it is set, the flag buckets
groups of that type instead of people. The new condition then serves every group of that type, and a user
evaluated without such a group is served nothing. Say groups when you report the change.
A multivariate flag needs `variant_key`, and every other flag rejects it. A release condition decides who
the flag serves and not which variant they get, so this also gives the named variant 100% of the variant
distribution and every other variant 0%. When the user says "roll it out to everyone" about a multivariate
flag, ask which variant they mean rather than guessing. To serve everyone and keep the current split between
variants, use `update-feature-flag`.
Check `experiment_set_metadata` in the definition you read. When it lists an experiment with `is_running`
true, ship the winner with `experiment-ship-variant`: that tool makes the same distribution change and also
ends the experiment and records its conclusion. This tool leaves the experiment running with no end date, so
every later exposure enters one variant and the comparison stops being valid. Use this tool on that flag
only when the user wants the audience changed and the experiment kept running.
Read the flag first and send the `version` that read returned. Returns 409 when anyone changed the flag
after that version, and writes nothing. Read the flag again, check what changed, and decide the rollout
against the current definition. Do not retry with the same version: after a call writes a change that
version is no longer current, so a blind retry is the same 409. A call that finds the flag already rolled
out to everyone writes nothing and returns the version unchanged.
Returns 400 when the flag is gated on early access enrollment, when a multivariate flag has no
`variant_key`, when the flag defines no such variant, or when `variant_key` is sent for a flag with no
variants. Returns 409 when an approval policy gates rollout changes.
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
hooks: featureFlags/conditionIdHooks
response:
include:
- id
- key
- active
- archived
- status
- version
- filters
feature-flag-rules-update:
operation: feature_flags_partial_update
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: true
idempotent: false
input_schema: FlagRulesV2UpdateInputSchema
enrich_url: '{id}'
title: Replace feature flag rules
description: >
Replace the rules of a feature flag whose `filters.version` is 2. Requires the flag's numeric ID; use
`feature-flag-get-definition-by-key` to get it from a key. For a flag without `filters.version` 2, use
`update-feature-flag` instead; this tool cannot convert a flag between the two formats.
Read the flag first with `feature-flag-get-definition` or `feature-flag-get-definition-by-key`. Build the
new `filters` from what you read and send the whole document: `version` 2, the same `return_type`,
`default_value` and the complete ordered `rules` list. The server replaces the stored `filters` with what
you send, so a rule you leave out is deleted. Rules are evaluated in order and the first rule that returns a
value wins.
Each rule you read has an `id`, and randomized rules (`percentage_rollout`, `experiment`) have a `seed`.
Send both unchanged on every rule you keep, edit or move, so the rule keeps its identity and nobody is
reassigned. Leave `id` and `seed` off a new rule; the server assigns them. Never invent an `id` or change a
`seed`: the write is refused.
Send the flag's top-level `version` from your read (not `filters.version`). Returns 409 when the flag
changed after that version, and writes nothing. Read the flag again, rebuild the change on the current rules
and send it with the new `version`. Do not retry with the same `version`.
Returns 400 naming the first invalid field when the document is invalid. Fix it and send the document again;
the next attempt can name another field. Returns 400 with code `reserved_config_version` ("filters.version
is reserved") when this project or this flag does not accept version 2 rule changes. Do not remove
`filters.version`. Report that to the user; do not work around it with `update-feature-flag`. This tool
changes only `filters`. Use `feature-flag-enable` and `feature-flag-disable` to turn the flag on or off.
feature_flag: feature-flag-rules-v2-mcp
response:
include:
- id
- key
- active
- version
- filters
feature-flag-set-release-condition-rollout:
operation: feature_flags_set_release_condition_rollout_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: false
enrich_url: '{id}'
title: Set feature flag release condition rollout
description: >
Set what percentage of one release condition's audience a feature flag is served to. Requires the flag's
numeric ID; use `feature-flag-get-definition-by-key` to get it from a key, or `feature-flag-get-all` to
search by key or name.
Changes `rollout_percentage` on the release condition at `condition_index` and nothing else. This tool never
accepts or replaces the `filters` object, so the condition's property filters, the other conditions, the
variants and the payloads cannot change.
Check `aggregation_group_type_index` on the condition, and on `filters` when the condition sets none. When
it is set, the flag buckets groups of that type instead of people, so 25 serves 25% of those groups rather
than 25% of users. Say groups when you report the change.
Read the flag first. `condition_index` counts the conditions in `filters.groups` from 0, and only the
definition you read says which condition is which, so never guess an index on a flag with more than one
condition. Send the `version` that same read returned. Returns 409 when anyone changed the flag after that
version, and writes nothing. Read the flag again, check the conditions still mean what you thought, and call
again with the new version. Do not retry with the same version: after a call writes a change that version is
no longer current, so a blind retry is the same 409. A call that sets the percentage the condition already
has writes nothing and returns the version unchanged.
On a multivariate flag this sets how many of the matching users or groups get a variant at all. It does not
change how the variants are split between them. When the user asks for a bare percentage on a multivariate
flag, ask which of the two they mean. Use `update-feature-flag` to change the split between variants.
Returns 400 when the flag has no release condition at that index, or when the percentage is outside 0
through 100. Returns 409 when an approval policy gates rollout changes.
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
hooks: featureFlags/conditionIdHooks
response:
include:
- id
- key
- active
- archived
- status
- version
- filters
feature-flag-unarchive:
operation: feature_flags_unarchive_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: true
enrich_url: '{id}'
title: Unarchive feature flag
description: >
Restore an archived feature flag to the default flag list. Requires the flag's numeric ID; pass
`{"archived":"true"}` to `feature-flag-get-all` to find archived flags.
Sets `archived` to false and changes nothing else. This tool never accepts or replaces the `filters` object.
There is no request body.
The flag stays turned off. Call `feature-flag-enable` when the user also wants it serving again. Unarchiving
a flag that is not archived succeeds and changes nothing, so retrying is safe.
Returns 400 when a release condition targets a deleted cohort. Remove that condition with
`update-feature-flag` first.
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
response:
include:
- id
- key
- active
- archived
- status
- version
feature-flags-activity-retrieve:
operation: feature_flags_activity_retrieve
enabled: true
scopes:
- activity_log:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get feature flag activity log
description: >
Get the audit trail for a specific feature flag by ID. Returns a paginated list of changes including who
made changes, what was changed, and when. Use limit and page query params for pagination.
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
feature-flags-bulk-delete-create:
operation: feature_flags_bulk_delete_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: true
idempotent: false
title: Bulk delete feature flags
description: >
Soft-delete multiple feature flags in one call. Provide either `ids` (explicit list of flag IDs) OR
`filters` (same shape as the list endpoint, e.g., search, active, type, tags), but not both. WARNING:
`filters` can match an unbounded number of flags. Preview matches via the list endpoint before calling this
with `filters`, and prefer explicit `ids` whenever the user has named specific flags. Flags linked to active
experiments, early access features, or that other flags depend on are skipped and reported in `errors`.
Returns `deleted` (with each flag's rollout state at deletion time) and `errors` arrays.
feature-flags-bulk-keys-retrieve:
operation: feature_flags_bulk_keys_retrieve
enabled: true
scopes:
- feature_flag:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Look up feature flag keys by ID
description: >
Resolve feature flag IDs to their string keys in one call. Pass `ids` as a list of integer flag IDs. Returns
`keys` as a mapping of stringified ID to key for the IDs that exist in this project. Useful when you have
IDs from another tool (e.g., dependent flags, scheduled changes) and need the keys for downstream calls.
feature-flags-bulk-update-tags-create:
operation: feature_flags_bulk_update_tags_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: true
idempotent: true
title: Bulk update tags on feature flags
description: >
Add, remove, or replace tags on multiple feature flags in one call. Provide `ids` (up to 500), an `action`
('add', 'remove', or 'set'), and a list of tag names. Returns `updated` (per-flag final tag list) and
`skipped` (flags missing or without edit permission, with reason).
feature-flags-copy-dependencies-check:
operation: feature_flags_copy_flags_dependency_requirements_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: true
destructive: false
idempotent: true
title: Check whether a flag's dependencies can be copied
description: >
Preview what a cross-project copy would do to a flag's transitive flag dependencies. Copies nothing and
changes nothing. Provide `feature_flag_key`, `from_project` (the source project ID) and
`target_project_ids`. Returns `can_copy_dependencies`, `dependency_count`, `copied_dependency_keys`
(dependencies missing from a target project, which a copy would create), `reused_dependency_keys`
(dependencies that already have an active same-key flag in every target project), plus `warnings` and a
human-readable `reason`. A false `can_copy_dependencies` does not always mean the copy is blocked: it is
also false when there is nothing to copy, because the flag has no dependencies or every dependency is
already satisfied in each target project. Read `warnings` to tell the two apart and report a problem only
when it is non-empty. Call this before every `feature-flags-copy-flags-create` copy; it is read-only and
returns an empty result when the flag has no dependencies. Set that tool's `copy_dependencies` only when the
user approves copying the keys this check reports. Requires write scope because it checks the same copy
eligibility and edit permissions the copy itself enforces.
include_params:
- feature_flag_key
- from_project
- target_project_ids
feature-flags-copy-flags-create:
operation: feature_flags_copy_flags_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: false
title: Copy feature flag across projects
description: >
Copy a feature flag from one project to other projects within the same organization. Provide the flag key,
source project ID, and a list of target project IDs. Optionally copy scheduled changes with copy_schedule.
Set copy_dependencies only when the user explicitly wants missing transitive flag dependencies copied too;
existing active same-key dependencies in target projects are reused, disabled same-key dependencies are left
untouched, and warnings explain any dependencies or schedules that could not be copied. Returns lists of
successful and failed copies.
feature-flags-dependent-flags-retrieve:
operation: feature_flags_dependent_flags_list
enabled: true
scopes:
- feature_flag:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get dependent feature flags
description: >
Get other active feature flags that depend on this flag. Use this to understand flag dependency chains
before making changes to a flag's rollout conditions or disabling it.
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
feature-flags-evaluation-reasons-retrieve:
operation: feature_flags_evaluation_reasons_retrieve
enabled: true
scopes:
- feature_flag:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get feature flag evaluation reasons
description: >
Debug why feature flags evaluate a certain way for a given user. Provide a distinct_id and optionally groups
to see each flag's evaluated value and the reason for that evaluation (e.g. condition_match,
no_condition_match, disabled). Pass flag_keys to scope the response to specific flags. This is strongly
recommended on projects with many flags, since omitting it returns an entry for every flag and can produce a
very large payload.
feature-flags-my-flags-retrieve:
operation: feature_flags_my_flags_retrieve
enabled: true
scopes:
- feature_flag:read
annotations:
readOnly: true
destructive: false
idempotent: true
list: true
title: Get my evaluated feature flags
description: >
List feature flags in the current project along with their evaluated value for the authenticated user (the
API key owner). Each item includes the flag definition and its current `value` (boolean for simple flags,
variant key string for multivariate flags, false if disabled). Pass `flag_keys` to scope the response to
specific flags. This is strongly recommended on projects with many flags, since omitting it returns an entry
for every flag and can produce a very large payload. Optionally pass `groups` as a JSON object to evaluate
group-based flags.
hooks: featureFlags/conditionIdHooks
feature-flags-status-retrieve:
operation: feature_flags_status_retrieve
enabled: true
scopes:
- feature_flag:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get feature flag status
description: >
Check the health and evaluation status of a feature flag by ID. Returns a status (active, stale, deleted, or
unknown) and a human-readable reason explaining the status. The status reflects recent evaluation (whether
the flag was called), NOT rollout completeness. To determine whether a flag is fully rolled out / GA, use
the returned `rollout` object: `effectively_full_rollout` (true when targeted to everyone with no
conditions), `has_targeting_conditions`, `max_rollout_percentage`, and `is_multivariate`. To scan the whole
project for stale flags, use `feature-flag-get-all` with `active: "STALE"`. That filter does not return a
never-called flag with an empty `groups` list in `filters`, even when this tool calls it stale.
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
feature-flags-test-evaluation-create:
operation: feature_flags_test_evaluation_create
enabled: true
scopes:
- feature_flag:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Test feature flag evaluation
description: >
Simulate how one feature flag (by numeric ID) would evaluate for a specific user, optionally at a past point
in time (`timestamp` reconstructs flag conditions and person properties as they existed then). Provide
`distinct_id` or `person_id` (mutually exclusive) and optionally `groups`. Returns the evaluated value with
detailed reasoning: which condition matched and the person properties used. Use this to debug or dry-run a
single flag; use `feature-flags-evaluation-reasons-retrieve` to see live evaluations across many flags for a
user, and `feature-flags-user-blast-radius-create` to size a release condition before applying it.
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
validators:
- validateDistinctIdPersonIdExclusive
ui_app: feature-flag-testing
feature-flags-user-blast-radius-create:
operation: feature_flags_user_blast_radius_create
enabled: true
scopes:
- feature_flag:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get user blast radius
description: >
Assess the impact of a feature flag release condition before applying it. Provide a condition object and
optionally a group_type_index to see how many users would be affected relative to the total user count.
scheduled-changes-create:
operation: scheduled_changes_create
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: false
title: Create a scheduled change
description: >
Schedule a future change to a feature flag. Supported operations: 'update_status' (enable/disable),
'add_release_condition', and 'update_variants'. Provide the flag ID as record_id, model_name as
"FeatureFlag", a payload with the operation and value, and a scheduled_at datetime.
exclude_params:
- executed_at
scheduled-changes-delete:
operation: scheduled_changes_destroy
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: true
idempotent: true
title: Delete a scheduled change
description: |
Delete a scheduled change by ID. This permanently removes the scheduled change and it will not be executed.
scheduled-changes-get:
operation: scheduled_changes_retrieve
enabled: true
scopes:
- feature_flag:read
annotations:
readOnly: true
destructive: false
idempotent: true
title: Get a scheduled change
description: >
Get a single scheduled change by ID. Returns the full details including the payload, schedule timing,
execution status, and any failure reason.
scheduled-changes-list:
operation: scheduled_changes_list
enabled: true
scopes:
- feature_flag:read
annotations:
readOnly: true
destructive: false
idempotent: true
list: true
title: List scheduled changes for feature flags
description: >
List scheduled changes in the current project. Filter by model_name=FeatureFlag and record_id to see
schedules for a specific flag. Returns pending, executed, and failed schedules with their payloads and
timing. Use this to check what changes are queued for a feature flag before modifying it.
param_overrides:
model_name:
description: |
Filter by model type. Use "FeatureFlag" to see feature flag schedules.
record_id:
description: |
Filter by the ID of a specific feature flag.
scheduled-changes-update:
operation: scheduled_changes_partial_update
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: true
title: Update a scheduled change
description: >
Update a pending scheduled change by ID. You can modify the payload, scheduled_at time, or recurrence
settings. Cannot change the target record (record_id) or model type (model_name).
exclude_params:
- executed_at
update-feature-flag:
operation: feature_flags_partial_update
enabled: true
scopes:
- feature_flag:write
annotations:
readOnly: false
destructive: false
idempotent: true
enrich_url: '{id}'
title: Update feature flag
description: >
Update a feature flag by numeric ID (partial update: only the fields you include are changed). Use this for
edits that have no dedicated tool, such as property filters, adding and removing release conditions, variant
definitions, payloads, tags and the description.
Prefer a dedicated tool whenever the request matches one. `feature-flag-enable`, `feature-flag-disable`,
`feature-flag-archive` and `feature-flag-unarchive` each change one state field and send no `filters`. A
targeting change someone else made between your read and your write is therefore not overwritten. Send
`active` or `archived` here only when the same request also changes targeting or another field, so the whole
edit lands in one write.
`feature-flag-set-release-condition-rollout` changes one release condition's percentage and
`feature-flag-roll-out-to-everyone` serves the flag to its whole audience. Both send no `filters` and both
refuse the write when the flag changed after the version you read, so a concurrent edit cannot be lost. On a
flag without `filters.version` 2, this tool does not check `version`, so it writes even when the flag
changed after your read. It replaces the whole `filters` object with your copy of it. Use it for a rollout
change only when those two tools cannot express it, such as changing the split between variants while
leaving the audience alone.
A flag whose `filters.version` is 2 requires `version` for any change, so read the flag first and send its
current `version`; never guess it. A stale `version` returns 409: read the flag again and decide against its
current state. Don't send `filters` for such a flag: its rules change through `feature-flag-rules-update`.
Rollout conditions, variants, and payloads live in the structured `filters` param, and sending `filters`
replaces the whole object, so read the flag first and merge your change. Each release condition you read has
a `condition_id`. Send it unchanged on every condition you keep, edit, or move, and leave it off a new
condition. A `condition_id` belongs to the flag you read it from, so leave it off a condition copied from a
different flag. Once any condition has a `condition_id`, a condition without one is treated as new. This
tool uses the ID to restore each condition's property types and targeting, so a reorder, deletion, or edit
keeps every condition on the persons or group type it targeted. If a `condition_id` matches no condition on
the flag, the flag may have changed after your read, and the update is refused. Read the flag again and
rebuild the update. When the flag targets groups, keep `type: "group"`, `group_type_index`, and
`filters.aggregation_group_type_index` in what you send; if you omit them this tool restores them from the
existing flag so group targeting is not silently converted to person targeting. When the flag's conditions
don't all target the same thing (some target persons and others a group type, or they target different group
types), set `aggregation_group_type_index` on every new condition. Use null for persons. If you send no
`condition_id` values, set `aggregation_group_type_index` on every condition whenever you add, remove,
reorder, or change the properties of conditions. Otherwise this tool can't tell which target each condition
keeps, and it refuses the update. Use `feature-flag-get-definition-by-key` when you have the string key: it
returns the numeric ID and the full definition in one call. Use `feature-flag-get-definition` when you
already have the ID. To apply a change at a future time instead, use `scheduled-changes-create`.
include_params:
- key
- name
- filters
- active
- archived
- tags
- evaluation_contexts
- is_remote_configuration
- ensure_experience_continuity
- evaluation_runtime
- bucketing_identifier
- version
param_overrides:
id:
cast: string-int
aliases:
- flagId
- flag_id
- feature_flag_id
- featureFlagId
filters:
input_schema: UpdateFeatureFlagFiltersSchema
is_remote_configuration:
description:
Whether this flag delivers a payload instead of gating a feature (Remote Config mode). When true, set the
delivered payload through the `filters` param under `filters.payloads.true` as a JSON-encoded
string. There is no dedicated payload parameter.
ensure_experience_continuity:
description:
Whether to persist the flag's value for a user across the anonymous-to-identified transition (the "persist
across authentication steps" option in the UI). Keeps a user's evaluated value stable once they log
in. Incompatible with `device_id` bucketing.
evaluation_runtime:
description:
Where this flag is allowed to evaluate — `server` (server-side SDKs only), `client` (client-side SDKs
only), or `all` (both). Defaults to `all`.
bucketing_identifier:
description:
Identifier used to bucket users into rollout percentages and variants — `distinct_id` (user ID, the
default) or `device_id`. Using `device_id` is incompatible with `ensure_experience_continuity=true`.
hooks: featureFlags/updateFeatureFlagHooks