From 6295a4b1231560ca776adb62f0d6b306ceec1a9d Mon Sep 17 00:00:00 2001 From: Kim Gustyr Date: Mon, 1 Jun 2026 17:23:27 +0100 Subject: [PATCH 1/2] docs(MCP): Rewrite MCP server page and generate the tool catalogue Rewrite the user-facing MCP server page for the self-built server, replacing the Gram-hosted page: - Cloud (`https://mcp.flagsmith.com`) and self-hosted (`https:///mcp/`) URLs - OAuth (auto-discovered) and `Authorization: Api-Key` authentication - Per-client install tabs: Claude Code, Cursor, Claude Desktop, Codex CLI, Windsurf, Gemini CLI, VS Code, and a generic fallback - Gram deprecation / migration callout, example prompts Generate the tool catalogue from the OpenAPI schema rather than hand-maintaining it, so descriptions stay in sync with the tools: - `manage.py generate_mcp_tool_catalogue` renders an aligned Markdown table of the MCP-tagged operations (verbatim `operationId` + `description`); `--exclude` omits tools already listed in another catalogue. - `make generate-docs` writes the core catalogue (`_mcp-tool-catalogue.md`); `api-tests-with-private-packages` derives the enterprise-only catalogue (`_mcp-tool-catalogue-enterprise.md`) against it. The page composes both via MDX imports (hence the `.md` -> `.mdx` rename). Contributes to Flagsmith/flagsmith-private#144. beep boop --- .../api-tests-with-private-packages.yml | 9 + api/Makefile | 1 + api/api/management/__init__.py | 0 api/api/management/commands/__init__.py | 0 .../commands/generate_mcp_tool_catalogue.py | 74 ++++++ .../api/test_generate_mcp_tool_catalogue.py | 58 +++++ .../_mcp-tool-catalogue-enterprise.md | 9 + .../_mcp-tool-catalogue.md | 38 +++ .../integrating-with-flagsmith/mcp-server.md | 106 -------- .../integrating-with-flagsmith/mcp-server.mdx | 242 ++++++++++++++++++ 10 files changed, 431 insertions(+), 106 deletions(-) create mode 100644 api/api/management/__init__.py create mode 100644 api/api/management/commands/__init__.py create mode 100644 api/api/management/commands/generate_mcp_tool_catalogue.py create mode 100644 api/tests/unit/api/test_generate_mcp_tool_catalogue.py create mode 100644 docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue-enterprise.md create mode 100644 docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md delete mode 100644 docs/docs/integrating-with-flagsmith/mcp-server.md create mode 100644 docs/docs/integrating-with-flagsmith/mcp-server.mdx diff --git a/.github/workflows/api-tests-with-private-packages.yml b/.github/workflows/api-tests-with-private-packages.yml index 411a8e3f19c4..0b9232664761 100644 --- a/.github/workflows/api-tests-with-private-packages.yml +++ b/.github/workflows/api-tests-with-private-packages.yml @@ -60,6 +60,15 @@ jobs: make integrate-private-tests rm -rf ${HOME}/.git-credentials + - name: Check MCP enterprise tool catalogue is up to date + env: + DOTENV_OVERRIDE_FILE: .env-ci + run: | + uv run python manage.py generate_mcp_tool_catalogue \ + --exclude ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md \ + > ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue-enterprise.md + git diff --exit-code ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue-enterprise.md + - name: Run Tests env: DOTENV_OVERRIDE_FILE: .env-ci diff --git a/api/Makefile b/api/Makefile index d07469bfbd9e..018529964130 100644 --- a/api/Makefile +++ b/api/Makefile @@ -164,6 +164,7 @@ integrate-private-tests: generate-docs: generate-flagsmith-sdk-openapi uv run flagsmith docgen metrics > ../docs/docs/deployment-self-hosting/observability/_metrics-catalogue.md uv run flagsmith docgen events > ../docs/docs/deployment-self-hosting/observability/_events-catalogue.md + uv run python manage.py generate_mcp_tool_catalogue > ../docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md .PHONY: add-known-sdk-version add-known-sdk-version: diff --git a/api/api/management/__init__.py b/api/api/management/__init__.py new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/api/api/management/commands/__init__.py b/api/api/management/commands/__init__.py new file mode 100644 index 000000000000..e69de29bb2d1 diff --git a/api/api/management/commands/generate_mcp_tool_catalogue.py b/api/api/management/commands/generate_mcp_tool_catalogue.py new file mode 100644 index 000000000000..92dc327079b4 --- /dev/null +++ b/api/api/management/commands/generate_mcp_tool_catalogue.py @@ -0,0 +1,74 @@ +import re +from argparse import ArgumentParser +from pathlib import Path +from typing import Any + +from django.core.management.base import BaseCommand + +from api.openapi import MCPSchemaGenerator + +_TOOL_NAME_RE = re.compile(r"^\| `([^`]+)`") + + +class Command(BaseCommand): + help = ( + "Generate a Markdown table of the MCP tool catalogue from the OpenAPI " + "schema. The set of tools reflects the apps installed in the current " + "environment, so private/enterprise tools only appear when their packages " + "are installed. Pass --exclude to omit tools already listed in an existing " + "catalogue (used to derive the enterprise-only catalogue against the core one)." + ) + + def add_arguments(self, parser: ArgumentParser) -> None: + parser.add_argument( + "--exclude", + type=Path, + default=None, + help="Path to an existing catalogue whose tools should be omitted.", + ) + + def handle(self, *args: Any, exclude: Path | None = None, **options: Any) -> None: + excluded = _read_tool_names(exclude) if exclude else set() + generator = MCPSchemaGenerator() + schema = generator.get_schema(request=None, public=True) + + rows = sorted( + (operation["operationId"], _one_line(operation.get("description", ""))) + for path_item in schema.get("paths", {}).values() + for operation in path_item.values() + if isinstance(operation, dict) and "operationId" in operation + if operation["operationId"] not in excluded + ) + + self.stdout.write(_render_table(("Tool", "Description"), rows)) + + +def _read_tool_names(path: Path) -> set[str]: + return { + match.group(1) + for line in path.read_text().splitlines() + if (match := _TOOL_NAME_RE.match(line)) + } + + +def _one_line(text: str) -> str: + return " ".join(text.split()).replace("|", "\\|") + + +def _render_table(header: tuple[str, str], rows: list[tuple[str, str]]) -> str: + # Render an aligned Markdown table matching Prettier's output so the committed + # catalogue is reproducible by `make generate-docs` and passes the docs + # Prettier check unchanged. + cells = [list(header)] + [[f"`{name}`", description] for name, description in rows] + widths = [max(len(row[col]) for row in cells) for col in range(len(header))] + lines = [ + _render_row(cells[0], widths), + "| " + " | ".join("-" * width for width in widths) + " |", + *(_render_row(row, widths) for row in cells[1:]), + ] + return "\n".join(lines) + + +def _render_row(cells: list[str], widths: list[int]) -> str: + padded = " | ".join(cell.ljust(width) for cell, width in zip(cells, widths)) + return f"| {padded} |" diff --git a/api/tests/unit/api/test_generate_mcp_tool_catalogue.py b/api/tests/unit/api/test_generate_mcp_tool_catalogue.py new file mode 100644 index 000000000000..926bdc251af7 --- /dev/null +++ b/api/tests/unit/api/test_generate_mcp_tool_catalogue.py @@ -0,0 +1,58 @@ +import io +from pathlib import Path + +from django.core.management import call_command + + +def _tool_names(table: str) -> list[str]: + return [line.split("`")[1] for line in table.splitlines() if line.startswith("| `")] + + +def test_generate_mcp_tool_catalogue__no_args__renders_sorted_mcp_tool_table() -> None: + # Given + out = io.StringIO() + + # When + call_command("generate_mcp_tool_catalogue", stdout=out) + + # Then + table = out.getvalue() + lines = table.splitlines() + assert lines[0].startswith("| Tool ") + assert set(lines[1].replace("|", "").replace(" ", "")) == {"-"} + + names = _tool_names(table) + assert "list_environments" in names + assert names == sorted(names) + assert "Lists all environments the user has access to" in table + + +def test_generate_mcp_tool_catalogue__exclude_file__omits_listed_tools( + tmp_path: Path, +) -> None: + # Given + exclude = tmp_path / "_mcp-tool-catalogue.md" + exclude.write_text("| Tool | Description |\n| `list_environments` | ... |\n") + out = io.StringIO() + + # When + call_command("generate_mcp_tool_catalogue", exclude=exclude, stdout=out) + + # Then + names = _tool_names(out.getvalue()) + assert "list_environments" not in names + assert "get_project" in names + + +def test_generate_mcp_tool_catalogue__description_with_pipe__escapes_pipe() -> None: + # Given / When + out = io.StringIO() + call_command("generate_mcp_tool_catalogue", stdout=out) + + # Then + # No raw pipe should appear inside a description cell (only as a column + # separator), so every table row has exactly two unescaped delimiters plus + # the leading and trailing ones. + for line in out.getvalue().splitlines(): + if line.startswith("| `"): + assert line.replace("\\|", "").count("|") == 3 diff --git a/docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue-enterprise.md b/docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue-enterprise.md new file mode 100644 index 000000000000..7f839381a5f2 --- /dev/null +++ b/docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue-enterprise.md @@ -0,0 +1,9 @@ +| Tool | Description | +| ------------------------------------------- | ------------------------------------------------------------------------------ | +| `add_feature_to_release_pipeline` | Adds a feature flag to a release pipeline for staged rollout. | +| `create_environment_feature_change_request` | Creates a new change request for feature flag modifications in an environment. | +| `get_release_pipeline` | Retrieves detailed information about a specific release pipeline. | +| `list_environment_change_requests` | Retrieves all change requests for an environment. | +| `list_organization_roles` | Retrieves all custom roles defined within the organisation. | +| `list_project_change_requests` | Retrieves all change requests for a project. | +| `list_project_release_pipelines` | Retrieves all release pipelines configured for the specified project. | diff --git a/docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md b/docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md new file mode 100644 index 000000000000..5c764c080e13 --- /dev/null +++ b/docs/docs/integrating-with-flagsmith/_mcp-tool-catalogue.md @@ -0,0 +1,38 @@ +| Tool | Description | +| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `create_environment_feature_version` | Creates a new version for a feature flag in a specific environment. Applies to environments with v2 feature versioning (use_v2_feature_versioning: true). | +| `create_environment_feature_version_state` | Creates a new feature state for a specific version in an environment. Applies to environments with v2 feature versioning (use_v2_feature_versioning: true). | +| `create_feature` | Creates a new feature flag in the specified project with default settings. | +| `create_feature_multivariate_option` | Creates a new multivariate option for a feature flag. | +| `create_organization_invite` | Send an invitation to join the organisation with specified role and permissions. | +| `create_project_segment` | Creates a new user segment for audience targeting within the project. | +| `create_segment_override` | Creates a segment override for a feature in an environment in a single call, setting both the segment binding and its value. Applies to environments without v2 feature versioning (use_v2_feature_versioning: false). | +| `delete_feature_multivariate_option` | Deletes a multivariate option. | +| `delete_feature_segment` | Deletes a segment override. Applies to environments without v2 feature versioning (use_v2_feature_versioning: false). | +| `get_environment_feature_version_states` | Retrieves feature state information for a specific version in an environment. Applies to environments with v2 feature versioning (use_v2_feature_versioning: true). | +| `get_environment_feature_versions` | Retrieves version information for a feature flag in a specific environment. Applies to environments with v2 feature versioning (use_v2_feature_versioning: true). | +| `get_feature_code_references` | Retrieves code references and usage information for the feature flag. | +| `get_feature_evaluation_data` | Retrieves evaluation data and analytics for a specific feature flag. | +| `get_feature_external_resources` | Retrieves external resources linked to the feature flag. | +| `get_feature_flag` | Retrieves detailed information about a specific feature flag. | +| `get_feature_health_events` | Retrieves feature health monitoring events and metrics for the project. | +| `get_project` | Retrieves comprehensive information about a specific project including configuration and statistics. | +| `get_project_segment` | Retrieves detailed information about a specific user segment. | +| `list_environments` | Lists all environments the user has access to | +| `list_feature_multivariate_options` | Retrieves all multivariate options for a feature flag. | +| `list_feature_segments` | Lists segment overrides for a feature in an environment. | +| `list_organization_groups` | Retrieves all permission groups within the organisation. | +| `list_organization_invites` | Retrieves all pending invitations for the organisation. | +| `list_organizations` | Lists all organisations accessible with the provided user API key. | +| `list_project_environments` | Retrieves all environments configured for the specified project. | +| `list_project_features` | Lists a project's feature flags (paginated). Pass `environment=` to also get each feature's live state for that environment in `environment_feature_state`, along with override counts. Works for both v1 and v2 versioned environments. | +| `list_project_segments` | Retrieves all user segments defined for audience targeting within the project. | +| `list_projects_in_organization` | Retrieves all projects within a specified organisation. | +| `publish_environment_feature_version` | Publishes a feature version to make it live in the environment. Applies to environments with v2 feature versioning (use_v2_feature_versioning: true). | +| `update_environment_feature_state` | Updates a feature state in an environment, including enabled status and value. Applies to environments without v2 feature versioning (use_v2_feature_versioning: false). | +| `update_environment_feature_version_state` | Updates an existing feature state for a specific version in an environment. Applies to environments with v2 feature versioning (use_v2_feature_versioning: true). | +| `update_feature` | Updates feature flag properties such as name and description. | +| `update_feature_multivariate_option` | Updates an existing multivariate option. | +| `update_feature_state` | Updates a feature state, including its enabled status and value. Also updates a segment override's value for environments without v2 feature versioning (use_v2_feature_versioning: false). | +| `update_project` | Updates project configuration settings such as the project name and feature visibility. | +| `update_project_segment` | Updates an existing user segment's properties and rules. | diff --git a/docs/docs/integrating-with-flagsmith/mcp-server.md b/docs/docs/integrating-with-flagsmith/mcp-server.md deleted file mode 100644 index 9839165a5b08..000000000000 --- a/docs/docs/integrating-with-flagsmith/mcp-server.md +++ /dev/null @@ -1,106 +0,0 @@ -# MCP Server - -The Flagsmith MCP Server provides programmatic access to the Flagsmith Admin API through the Model Context Protocol. This enables AI assistants and agents to interact with your feature flag infrastructure, including managing flags, segments, and release workflows. The server is compatible with MCP-enabled IDE extensions (such as Cursor), CLI tools (such as Claude Code), and custom AI agents integrated into CI/CD pipelines. - -## What is MCP? - -[Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that lets AI assistants connect to external tools and services. Think of it as giving your AI a set of hands to actually *do* things, not just talk about them. - -## What Can You Do With It? - -The MCP Server exposes the Flagsmith Admin API, giving your AI access to: - -- **Organisations & Projects** — List and navigate your Flagsmith workspace -- **Feature Flags** — Create, update, and manage flags across environments -- **Segments** — Build and modify user segments for precise targeting -- **Release Pipelines** — Orchestrate controlled rollouts -- **Change Requests** — Create and manage approval workflows -- **Multivariate Testing** — Configure A/B test variations - -Use it for human-in-the-loop workflows (asking your IDE assistant to toggle a flag), or fully automated pipelines (letting an agent manage progressive rollouts). - -## Installation - -Head to our installation page and pick your client: - -👉 **[Install the Flagsmith MCP Server](https://app.getgram.ai/mcp/flagsmith-mcp/install)** - -We support Cursor, Claude Code, Claude Desktop, Windsurf, Gemini CLI, Codex CLI, and any other client that supports MCP servers. - -### Authentication - -The MCP Server supports two authentication methods. You can use either one — both work side by side. - -#### 1. OAuth (Recommended for SaaS users) - -OAuth lets you authenticate directly in your browser — no API keys to manage. Simply add the MCP server to your client and it will redirect you to the Flagsmith OAuth flow where you can log in and authorise access. - -For **Claude Code**: - -```bash -claude mcp add --transport http "flagsmith" \ - "https://app.getgram.ai/mcp/flagsmith-mcp" -``` - -For **Codex CLI**: - -```json -[mcp_servers.flagsmith] -url = "https://app.getgram.ai/mcp/flagsmith-mcp" -``` - -For other clients, visit the **[installation page](https://app.getgram.ai/mcp/flagsmith-mcp/install)** for client-specific instructions. - -> OAuth is currently available for SaaS users only. Self-hosted and private cloud customers should use an Organisation API Key or contact our team. - -#### 2. Organisation API Key - -Alternatively, you can authenticate using an Organisation API Key: - -1. Go to **Organisation Settings** in your Flagsmith dashboard -2. Generate a new API Key -3. Set your environment variable with the `Api-Key` prefix: - -```bash -MCP_FLAGSMITH_TOKEN_AUTH="Api-Key YOUR_API_KEY_HERE" -``` - -> ⚠️ **Important**: The `Api-Key ` prefix is required. The value of your environment variable should look like `Api-Key ser.abc123...`, not just the key itself. - -### Self-Hosted Flagsmith and Private Cloud - -Running your own Flagsmith instance or using our Private Cloud? Use Organisation API Key authentication, then point the MCP Server at your API by adding the following headers during installation: - -```bash -claude mcp add --transport http "flagsmith" \ - "https://app.getgram.ai/mcp/flagsmith-mcp" \ - --header 'Mcp-Flagsmith-Token-Auth:${MCP_FLAGSMITH_TOKEN_AUTH}' \ - --header 'Mcp-Flagsmith-Server-Url:https://your-flagsmith-instance.com' -``` - -## Example Use Cases - -**For Developers** -- "Create a feature flag called `new_checkout_flow` and turn it on in the staging environment" -- "What segments exist in the mobile-app project?" -- "Add a multivariate option to the `button_color` flag" - -**For Release Managers** -- "Show me all pending change requests for the production environment" -- "Add the `premium_features` flag to the Q1 release pipeline" -- "List all features that have been modified in the last week" - -**For DevOps & Automation** -- Build agents that automatically create kill switches for new deployments -- Integrate flag validation and management into your CI/CD pipelines -- Automate segment updates based on external analytics data - -## Early Access — We Want Your Feedback! 🚀 - -This is an early release, and we're actively developing it alongside customers like you. Things might be rough around the edges, but that's where you come in. - -**Found a bug? Have an idea? Something confusing?** - -We'd love to hear from you - drop our support a message at [support@flagsmith.com](mailto:support@flagsmith.com) - -Your feedback directly shapes what we build next. Let's make this awesome together. \ No newline at end of file diff --git a/docs/docs/integrating-with-flagsmith/mcp-server.mdx b/docs/docs/integrating-with-flagsmith/mcp-server.mdx new file mode 100644 index 000000000000..92a27758e8ea --- /dev/null +++ b/docs/docs/integrating-with-flagsmith/mcp-server.mdx @@ -0,0 +1,242 @@ +--- +description: Connect AI assistants and agents to Flagsmith using the Model Context Protocol (MCP). +sidebar_label: MCP Server +sidebar_position: 30 +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import McpToolCatalogue from './_mcp-tool-catalogue.md'; +import McpToolCatalogueEnterprise from './_mcp-tool-catalogue-enterprise.md'; + +# MCP Server + +The Flagsmith MCP Server gives AI assistants and agents programmatic access to the Flagsmith Admin API through the +[Model Context Protocol](https://modelcontextprotocol.io). Your assistant can manage feature flags, segments, +multivariate options, and release workflows on your behalf — in a human-in-the-loop IDE session, or fully automated in a +CI/CD pipeline. + +It works with any MCP client that supports remote (Streamable HTTP) servers, including Claude Code, Claude Desktop, +Cursor, and Codex. + +## Connecting to the server + +The server is reachable over HTTP and you connect your client directly to it — there is nothing to install or run +yourself. + +| Deployment | MCP URL | +| --------------------------- | --------------------------- | +| Flagsmith SaaS (cloud) | `https://mcp.flagsmith.com` | +| Self-hosted / private cloud | Your MCP server base URL | + +For self-hosted instances the MCP server is part of your Flagsmith deployment; use your MCP server base URL wherever the +examples below use the SaaS URL. + +## Authentication + +The server supports two authentication methods. Use whichever suits your client; both work side by side. + +### OAuth (interactive clients) + +For interactive clients — IDEs, desktop apps, CLIs you drive by hand — OAuth is the simplest option, with no API keys to +manage. The client discovers the OAuth configuration automatically from the MCP URL: on first connection it opens your +browser, you log in to Flagsmith and authorise access, and the client stores the resulting token. + +### API key (CI and non-interactive agents) + +For automation — CI jobs, headless agents — authenticate with an +[Organisation API key](/integrating-with-flagsmith/flagsmith-api-overview/admin-api/authentication) by sending it in the +`Authorization` header: + +``` +Authorization: Api-Key +``` + +:::caution + +The `Api-Key ` prefix is required. The header value should look like `Api-Key ser.abc123…`, not the key on its own. + +::: + +## Installing in your client + +The examples below use the SaaS URL. For self-hosted, substitute your MCP server base URL. + + + + +```bash +claude mcp add --transport http flagsmith https://mcp.flagsmith.com +``` + +Then run `/mcp` in Claude Code to complete the OAuth login. For non-interactive use, pass the API key as a header +instead: + +```bash +claude mcp add --transport http flagsmith https://mcp.flagsmith.com \ + --header "Authorization: Api-Key " +``` + + + + +Add the server to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project): + +```json +{ + "mcpServers": { + "flagsmith": { + "url": "https://mcp.flagsmith.com" + } + } +} +``` + +To use an API key instead of OAuth, add a `headers` block: + +```json +{ + "mcpServers": { + "flagsmith": { + "url": "https://mcp.flagsmith.com", + "headers": { "Authorization": "Api-Key " } + } + } +} +``` + + + + +Open **Settings → Connectors → Add custom connector**, give it the name `Flagsmith` and the URL +`https://mcp.flagsmith.com`, then connect and complete the OAuth login. + + + + +Add the server to `~/.codex/config.toml`: + +```toml +[mcp_servers.flagsmith] +url = "https://mcp.flagsmith.com" +``` + + + + +Add the server to `~/.codeium/windsurf/mcp_config.json`: + +```json +{ + "mcpServers": { + "flagsmith": { + "serverUrl": "https://mcp.flagsmith.com" + } + } +} +``` + +For an API key instead of OAuth, add `"headers": { "Authorization": "Api-Key " }` to the server entry. + + + + +Add the server to `~/.gemini/settings.json`: + +```json +{ + "mcpServers": { + "flagsmith": { + "httpUrl": "https://mcp.flagsmith.com" + } + } +} +``` + +For an API key instead of OAuth, add `"headers": { "Authorization": "Api-Key " }` to the server entry. + + + + +Add the server to `.vscode/mcp.json` (workspace) or your user `mcp.json`: + +```json +{ + "servers": { + "flagsmith": { + "type": "http", + "url": "https://mcp.flagsmith.com" + } + } +} +``` + +For an API key instead of OAuth, add `"headers": { "Authorization": "Api-Key " }` to the server entry. + + + + +Any other client that supports remote (Streamable HTTP) MCP servers can connect by pointing it at the MCP URL above and +using either OAuth or the `Authorization: Api-Key` header. + + + + +## Available tools + +The tools available to your assistant depend on what your Flagsmith deployment has installed. The core tools below are +available on every deployment. The [enterprise tools](#enterprise-tools) require a paid SaaS plan or a self-hosted +Enterprise deployment, and only appear when those features are present. + +### Core tools + + + +### Enterprise tools + +Available on paid SaaS plans and self-hosted Enterprise deployments. + + + +## Migrating from the Gram-hosted server + +:::caution Deprecation + +The previous MCP server was hosted on Gram at `https://app.getgram.ai/mcp/flagsmith-mcp`. It is deprecated and will be +shut down on **30 June 2026**. + +Point your client at `https://mcp.flagsmith.com` instead. Tool names are unchanged, so no other changes to your prompts +or automations are needed. If you authenticated with a custom `Mcp-Flagsmith-Token-Auth` header, switch to the standard +`Authorization: Api-Key ` header (or OAuth). + +::: + +## Example prompts + +For developers: + +- "Create a feature flag called `new_checkout_flow` and turn it on in the staging environment." +- "What segments exist in the mobile-app project?" +- "Add a multivariate option to the `button_color` flag." + +For release managers: + +- "Show me all pending change requests for the production environment." +- "Add the `premium_features` flag to the Q1 release pipeline." + +For DevOps and automation: + +- Build agents that create kill switches for new deployments. +- Integrate flag validation and management into your CI/CD pipelines. +- Automate segment updates based on external analytics data. + +## Early Access — We Want Your Feedback! 🚀 + +This is an early release, and we're actively developing it alongside customers like you. Things might be rough around +the edges, but that's where you come in. + +**Found a bug? Have an idea? Something confusing?** + +We'd love to hear from you — drop our support team a message at [support@flagsmith.com](mailto:support@flagsmith.com). + +Your feedback directly shapes what we build next. Let's make this awesome together. From ef6914bd564ec0d86c4e7522772c559750431283 Mon Sep 17 00:00:00 2001 From: Kim Gustyr Date: Wed, 3 Jun 2026 10:46:59 +0100 Subject: [PATCH 2/2] docs(MCP): add stdio/uvx option to each client install tab beep boop --- .../integrating-with-flagsmith/mcp-server.mdx | 98 ++++++++++++++++++- 1 file changed, 95 insertions(+), 3 deletions(-) diff --git a/docs/docs/integrating-with-flagsmith/mcp-server.mdx b/docs/docs/integrating-with-flagsmith/mcp-server.mdx index 92a27758e8ea..98fa058559e5 100644 --- a/docs/docs/integrating-with-flagsmith/mcp-server.mdx +++ b/docs/docs/integrating-with-flagsmith/mcp-server.mdx @@ -21,8 +21,9 @@ Cursor, and Codex. ## Connecting to the server -The server is reachable over HTTP and you connect your client directly to it — there is nothing to install or run -yourself. +The server is reachable over HTTP and you connect your client directly to it — on Flagsmith SaaS there is nothing to +install or run yourself. If you'd rather run the server as a local subprocess, each client below also has a stdio option +(launched with [uv](https://docs.astral.sh/uv/); authenticate with an API key, since stdio has no interactive OAuth). | Deployment | MCP URL | | --------------------------- | --------------------------- | @@ -77,6 +78,15 @@ claude mcp add --transport http flagsmith https://mcp.flagsmith.com \ --header "Authorization: Api-Key " ``` +Or run it locally over stdio: + +```bash +claude mcp add flagsmith \ + --env TRANSPORT=stdio \ + --env FLAGSMITH_API_TOKEN= \ + -- uvx --from "git+https://github.com/Flagsmith/flagsmith.git@main#subdirectory=mcp" flagsmith-mcp +``` + @@ -105,12 +115,40 @@ To use an API key instead of OAuth, add a `headers` block: } ``` +Or run it locally over stdio: + +```json +{ + "mcpServers": { + "flagsmith": { + "command": "uvx", + "args": ["--from", "git+https://github.com/Flagsmith/flagsmith.git@main#subdirectory=mcp", "flagsmith-mcp"], + "env": { "TRANSPORT": "stdio", "FLAGSMITH_API_TOKEN": "" } + } + } +} +``` + Open **Settings → Connectors → Add custom connector**, give it the name `Flagsmith` and the URL `https://mcp.flagsmith.com`, then connect and complete the OAuth login. +To run it locally over stdio instead, add it to your `claude_desktop_config.json`: + +```json +{ + "mcpServers": { + "flagsmith": { + "command": "uvx", + "args": ["--from", "git+https://github.com/Flagsmith/flagsmith.git@main#subdirectory=mcp", "flagsmith-mcp"], + "env": { "TRANSPORT": "stdio", "FLAGSMITH_API_TOKEN": "" } + } + } +} +``` + @@ -121,6 +159,15 @@ Add the server to `~/.codex/config.toml`: url = "https://mcp.flagsmith.com" ``` +Or run it locally over stdio: + +```toml +[mcp_servers.flagsmith] +command = "uvx" +args = ["--from", "git+https://github.com/Flagsmith/flagsmith.git@main#subdirectory=mcp", "flagsmith-mcp"] +env = { TRANSPORT = "stdio", FLAGSMITH_API_TOKEN = "" } +``` + @@ -138,6 +185,20 @@ Add the server to `~/.codeium/windsurf/mcp_config.json`: For an API key instead of OAuth, add `"headers": { "Authorization": "Api-Key " }` to the server entry. +Or run it locally over stdio: + +```json +{ + "mcpServers": { + "flagsmith": { + "command": "uvx", + "args": ["--from", "git+https://github.com/Flagsmith/flagsmith.git@main#subdirectory=mcp", "flagsmith-mcp"], + "env": { "TRANSPORT": "stdio", "FLAGSMITH_API_TOKEN": "" } + } + } +} +``` + @@ -155,6 +216,20 @@ Add the server to `~/.gemini/settings.json`: For an API key instead of OAuth, add `"headers": { "Authorization": "Api-Key " }` to the server entry. +Or run it locally over stdio: + +```json +{ + "mcpServers": { + "flagsmith": { + "command": "uvx", + "args": ["--from", "git+https://github.com/Flagsmith/flagsmith.git@main#subdirectory=mcp", "flagsmith-mcp"], + "env": { "TRANSPORT": "stdio", "FLAGSMITH_API_TOKEN": "" } + } + } +} +``` + @@ -173,11 +248,28 @@ Add the server to `.vscode/mcp.json` (workspace) or your user `mcp.json`: For an API key instead of OAuth, add `"headers": { "Authorization": "Api-Key " }` to the server entry. +Or run it locally over stdio: + +```json +{ + "servers": { + "flagsmith": { + "type": "stdio", + "command": "uvx", + "args": ["--from", "git+https://github.com/Flagsmith/flagsmith.git@main#subdirectory=mcp", "flagsmith-mcp"], + "env": { "TRANSPORT": "stdio", "FLAGSMITH_API_TOKEN": "" } + } + } +} +``` + Any other client that supports remote (Streamable HTTP) MCP servers can connect by pointing it at the MCP URL above and -using either OAuth or the `Authorization: Api-Key` header. +using either OAuth or the `Authorization: Api-Key` header. Clients that support stdio servers can instead launch it with +`uvx --from "git+https://github.com/Flagsmith/flagsmith.git@main#subdirectory=mcp" flagsmith-mcp`, setting +`TRANSPORT=stdio` and `FLAGSMITH_API_TOKEN`.