MCP

Basestack Flags exposes a remote Model Context Protocol endpoint at:

https://<your-flags-api-host>/mcp

Create a tokenCopy Anchor Link

Open your profile settings and go to MCP Tokens. Create a token and copy it immediately. MCP tokens are read-only by default; select the write option only when the client needs to create projects, create or edit flags, post or edit comments, toggle flags, or change an environment's preview, expiration, or remote configuration.

An MCP token works across every Flags project its owner can access, including projects they join later. Operations in existing projects check the owner's current membership and role, so removing access or changing a role takes effect immediately. Creating a project makes the token owner a member and owner.

Project API tokens remain under each project's Settings → Tokens page. Those credentials are project-specific and cannot be used with the MCP endpoint.

Connect a clientCopy Anchor Link

MCP clients use different configuration formats. Store the token in an environment variable before starting a local client:

export BASESTACK_FLAGS_MCP_TOKEN="<flags-mcp-token>"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "basestack-flags": {
        "type": "remote",
        "url": "https://<your-flags-api-host>/mcp",
        "disabled": false,
        "oauth": false,
        "headers": {
          "Authorization": "Bearer {env:BASESTACK_FLAGS_MCP_TOKEN}"
        }
      }
    }
  }
}

Never commit an MCP token to a shared client configuration or source control.

Available toolsCopy Anchor Link

• list_projects
• get_project
• list_environments
• list_flags
• get_flag
• list_code_references
• list_flag_history
• list_flag_comments
• create_project
• create_flag
• update_flag
• update_flag_preview_content
• update_flag_environment
• set_flag_enabled
• create_flag_comment
• update_flag_comment

Resource tools accept a projectId; call list_projects to discover valid projects. Read tools are available to every project member. create_project requires a write-enabled token and makes the token owner a member and owner. Other write tools are visible only to write-enabled tokens and still enforce the same project roles as the dashboard.

list_code_references returns stored source snippets and location metadata for code that references feature flags. Pass slug to restrict results to one flag, or omit it to retrieve recent references across the project. Results are bounded with limit (100 by default, 250 maximum), and the tool never modifies uploaded references.

list_flag_history returns the persisted audit history for flag configuration changes, optionally bounded by an ISO 8601 date range. Basestack currently does not collect per-evaluation events, so evaluation counts, users, variants, and runtime analytics are not available through MCP.

update_flag_preview_content changes the Feature Preview title or plain-text description for a flag across all environments. Omitted fields are preserved; pass null to clear the title or description.

update_flag_environment changes one environment without altering its enabled state. It accepts isPreview, an ISO 8601 expiredAt value (null clears the expiration), and remoteConfig (null clears the stored payload). At least one of these fields is required.

list_flag_comments returns comments on one flag, newest first. Comments are shared across that flag's environments. Results are bounded with limit (20 by default, 50 maximum). Pass the returned cursor to load older comments. Each comment includes its id, author, timestamps, and whether the token owner can edit it.

create_flag_comment and update_flag_comment require a write-enabled token and the same project role required to comment in the dashboard. Comments are plain text, from 1 to 2,000 characters. Posting a comment also follows the flag for email updates and is limited to 10 comments per project every 5 minutes. You can edit only your own comments. MCP cannot delete comments, including your own.

Prompt examplesCopy Anchor Link

You can refer to projects, environments, and flags by name. Ask the client to discover their IDs before it performs another operation.

Explore your projectsCopy Anchor Link

List every Flags project I can access. For each project, show its name, project
ID, and my role. Do not make any changes.

Inspect a flag across environmentsCopy Anchor Link

In the "Checkout" project, find the "checkout-redesign" flag and show whether
it is enabled in every environment. Include the project and environment IDs.
Do not change anything.

Search for related flagsCopy Anchor Link

In the "Web App" project, search for flags containing "onboarding". Summarize
what each flag controls, then inspect the matching flags across all
environments. Do not make any changes.

Prepare a new flagCopy Anchor Link

In the "Checkout" project, prepare a new flag named "checkout-redesign".
Configure it in every project environment, enabled only in develop and
disabled everywhere else. First list the environments and show me the complete
creation plan, then wait for my approval before calling create_flag.

Prepare a new projectCopy Anchor Link

Prepare a new Flags project named "Checkout". Explain which default
environments will be created and confirm that I will become its owner. Wait for
my approval before calling create_project.

Change one environmentCopy Anchor Link

In the "Web App" project, prepare to enable "maintenance-banner" in Staging
only. Confirm its current state and the target environment ID, then wait for my
approval before calling set_flag_enabled. Do not change any other environment.

Edit an existing flagCopy Anchor Link

In the "Checkout" project, prepare to rename "checkout-redesign" to
"checkout-refresh", update its description, and set a new payload in Development
only. Show the current values and target environment ID, then wait for my
approval before calling update_flag. Preserve all enabled states, preview
settings, expiration dates, and payloads in other environments.

Update Feature Preview contentCopy Anchor Link

In the "Checkout" project, set the Feature Preview title for "checkout-refresh"
to "Try the redesigned checkout" and its description to "A faster checkout for
selected customers." Show the proposed content and wait for my approval before
calling update_flag_preview_content. Preserve its preview state, expiration,
remote configuration, and enabled states.

Change environment configurationCopy Anchor Link

In the "Checkout" project, inspect "checkout-refresh" in Production. Prepare to
enable preview, set its expiration to 2026-12-01T00:00:00.000Z, and replace its
remote configuration with {"checkoutVersion": 3}. Show the current values and
wait for my approval before calling update_flag_environment. Preserve its
enabled state and every other environment.

Find code references for a flagCopy Anchor Link

In the "Checkout" project, use list_code_references to find every stored code
reference for "checkout-refresh". Show each repository, branch, file path, line
number, and source snippet. Do not make any changes.

Review project-wide code referencesCopy Anchor Link

Use list_code_references without a slug to show the 100 most recent code
references across the "Checkout" project. Group them by flag slug and file.
Do not make any changes.

Read flag commentsCopy Anchor Link

In the "Checkout" project, use list_flag_comments to show the latest comments
on "checkout-refresh". Include each author, whether the comment was edited, and
the comment id. Do not post, edit, or delete anything.

Add a commentCopy Anchor Link

In the "Checkout" project, prepare a comment on "checkout-refresh": "Staging
tests passed. Wait until Friday's release before enabling this in production."
Show the exact text and confirm that posting will also follow the flag. Wait
for my approval before calling create_flag_comment. Do not edit or delete any
existing comment.

Edit your own commentCopy Anchor Link

In the "Checkout" project, list comments on "checkout-refresh" and find the
latest comment I wrote. Prepare to replace it with "Staging tests passed.
Enable in production after Friday's release." Show the comment id and the new
text, then wait for my approval before calling update_flag_comment. Do not
change anyone else's comments, and do not delete anything.

Review flag activityCopy Anchor Link

Show the 20 most recent configuration changes for "checkout-refresh" in the
"Checkout" project using list_flag_history. Summarize who changed it, what type
of change occurred, and when. Do not make any changes.

For the strongest protection against accidental changes, use a read-only token. Instructions such as “wait for my approval” depend on the connected client's confirmation behavior and do not replace token permissions.

Billing usageCopy Anchor Link

Every authenticated HTTP request to the Flags MCP endpoint records one request against the token owner's api_requests billing meter. Protocol requests such as initialize and tools/list count in the same way as tools/call. One HTTP request always counts as one request, regardless of which tool it invokes or whether the tool succeeds.