feat(MCP): Run an MCP server out of OpenAPI specs (#7670)

Co-authored-by: Kim Gustyr <kim.gustyr@flagsmith.com>

Author: emyller

.github/workflows/mcp-pull-request.yml

@@ -0,0 +1,56 @@
+name: MCP Pull Request
+
+permissions:
+  contents: read # For actions/checkout
+
+on:
+  pull_request:
+    paths:
+      - mcp/**
+      - .github/**
+    types: [opened, synchronize, reopened, ready_for_review]
+  push:
+    paths:
+      - mcp/**
+      - .github/**
+    branches:
+      - main
+
+defaults:
+  run:
+    working-directory: mcp
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    name: MCP Tests
+
+    steps:
+      - name: Cloning repo
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+          enable-cache: true
+          cache-dependency-glob: mcp/uv.lock
+
+      - name: Install dependencies
+        run: make install
+
+      - uses: liskin/gh-problem-matcher-wrap@v2
+        with:
+          action: add
+          linters: mypy
+
+      - name: Check for new typing errors
+        run: make typecheck
+
+      - uses: liskin/gh-problem-matcher-wrap@v2
+        with:
+          action: remove
+          linters: mypy
+
+      - name: Run tests
+        run: make test

.pre-commit-config.yaml

@@ -1,14 +1,24 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    # Ruff version.
     rev: v0.15.12
+    # Each project is linted under its own config; the global hook runs once per project.
     hooks:
-      # Run the linter.
       - id: ruff
+        name: api-lint
+        files: ^api/
         args: [--config, api/pyproject.toml, --config, "src = ['api']", --fix]
-      # Run the formatter.
       - id: ruff-format
+        name: api-format
+        files: ^api/
         args: [--config, api/pyproject.toml, --config, "src = ['api']"]
+      - id: ruff
+        name: mcp-lint
+        files: ^mcp/
+        args: [--config, mcp/pyproject.toml, --config, "src = ['mcp/src']", --fix]
+      - id: ruff-format
+        name: mcp-format
+        files: ^mcp/
+        args: [--config, mcp/pyproject.toml, --config, "src = ['mcp/src']"]
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0
@@ -34,12 +44,22 @@ repos:
         entry: make -C api generate-docs
         pass_filenames: false
         types_or: [python, toml]
-      - id: python-typecheck
-        name: python-typecheck
+      - id: api-typecheck
+        name: api-typecheck
         language: system
         entry: uv run --directory api mypy .
         require_serial: true
         pass_filenames: false
+        files: ^api/
+        types: [python]
+        stages: [pre-push]
+      - id: mcp-typecheck
+        name: mcp-typecheck
+        language: system
+        entry: uv run --directory mcp mypy .
+        require_serial: true
+        pass_filenames: false
+        files: ^mcp/
         types: [python]
         stages: [pre-push]
 
@@ -52,7 +72,11 @@ repos:
     rev: 0.11.14  # Ensure this matches the version in api/pyproject.toml
     hooks:
       - id: uv-lock
+        name: api-lockcheck
         args: ["--project", "api", "--check"]
+      - id: uv-lock
+        name: mcp-lockcheck
+        args: ["--project", "mcp", "--check"]
 
   - repo: https://github.com/renovatebot/pre-commit-hooks
     rev: 43.205.2
@@ -65,5 +89,5 @@ default_install_hook_types: [pre-commit, pre-push]
 default_stages: [pre-commit]
 
 ci:
-  skip: [generate-docs, python-typecheck, renovate-config-validator]
+  skip: [generate-docs, api-typecheck, mcp-typecheck, renovate-config-validator]
   autoupdate_commit_msg: "ci: pre-commit autoupdate"

AGENTS.md

@@ -8,3 +8,4 @@ Install Git hooks: `make install-hooks`
 For backend code, read @api/README.md
 For frontend code, read @frontend/README.md
 For docs.flagsmith.com source, read @docs/README.md
+For MCP code, read @mcp/README.md

mcp/.gitignore

@@ -0,0 +1,15 @@
+# Python / uv
+.venv
+__pycache__/
+*.py[cod]
+dist/
+*.egg-info/
+
+# Test / type / lint caches
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/

mcp/Makefile

@@ -0,0 +1,20 @@
+.PHONY: install
+install:
+	uv sync --frozen $(opts)
+
+.PHONY: serve
+serve:
+	uv run flagsmith-mcp
+
+.PHONY: lint
+lint:
+	uv run ruff check $(opts)
+	uv run ruff format --check $(opts)
+
+.PHONY: typecheck
+typecheck:
+	uv run mypy .
+
+.PHONY: test
+test:
+	uv run pytest $(opts)

mcp/README.md

@@ -0,0 +1,13 @@
+# Flagsmith MCP Server
+
+## Local development
+
+This application assumes the following software is installed:
+- [uv](https://docs.uv.dev/)
+- [GNU Make](https://www.gnu.org/software/make/)
+
+Install dependencies with `make install`.
+
+Run the server with `make serve`.
+
+Run tests with `make test`.

mcp/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "flagsmith-mcp"
+version = "0.1.0"
+description = "An MCP server connecting to the Flagsmith API."
+authors = [{ name = "Flagsmith", email = "support@flagsmith.com" }]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp>=3.3.1,<4.0.0",  # Base MCP functionality
+    "pydantic-settings>=2.0.0,<3.0.0",  # Environment-driven configuration
+]
+
+[project.scripts]
+flagsmith-mcp = "flagsmith_mcp.server:run"
+
+[dependency-groups]
+dev = [
+    "mypy>=2.1.0,<3.0.0",  # Static type checking
+    "openapi-pydantic>=0.5.0,<1.0.0",  # Build OpenAPI specs as fixtures
+    "pytest>=9.0.3,<10.0.0",  # Run tests
+    "pytest-asyncio>=1.3.0,<2.0.0",  # Run asynchronous tests
+    "pytest-cov>=7.0.0,<8.0.0",  # Measure test coverage
+    "pytest-httpx>=0.35.0,<1.0.0",  # Mock HTTP interactions
+    "ruff>=0.15.12,<0.16.0",  # Lint and format
+]
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+addopts = "--cov=flagsmith_mcp --cov-report=term-missing --cov-fail-under=100"
+
+[tool.coverage.run]
+branch = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+# Establish parity with flake8 + isort
+select = ["C901", "E4", "E7", "E9", "F", "I", "W"]
+
+[tool.mypy]
+strict = true
+show_absolute_path = true

mcp/src/flagsmith_mcp/__init__.py

@@ -0,0 +1,28 @@
+from collections.abc import Generator
+
+import httpx
+from fastmcp.server.dependencies import get_http_headers
+
+
+class FlagsmithAuth(httpx.Auth):
+    def __init__(self, global_master_api_key: str | None = None) -> None:
+        self._global_master_api_key = global_master_api_key
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Generator[httpx.Request, httpx.Response, None]:
+        if "authorization" not in request.headers:
+            # Prefer the caller's forwarded MCP `--header`; fall back to the
+            # server's own static token (the only credential under stdio).
+            forwarded = get_http_headers(include={"authorization"})
+            if (
+                authorization := forwarded.get("authorization")
+                or self._global_authorization_value()
+            ):
+                request.headers["authorization"] = authorization
+        yield request
+
+    def _global_authorization_value(self) -> str | None:
+        if self._global_master_api_key:
+            return f"Api-Key {self._global_master_api_key}"
+        return None

mcp/src/flagsmith_mcp/auth.py

@@ -0,0 +1,33 @@
+from typing import Literal
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings
+
+Transport = Literal["http", "stdio"]
+
+
+class Settings(BaseSettings):
+    model_config = {"use_attribute_docstrings": True}
+
+    flagsmith_api_url: str = Field(
+        default="https://api.flagsmith.com",
+    )
+    """Flagsmith API base URL."""
+    flagsmith_api_token: str | None = Field(
+        default=None,
+    )
+    """Flagsmith Master API Key. Required for stdio transport."""
+    transport: Transport = Field(
+        default="http",
+    )
+    """MCP transport to use."""
+
+    @model_validator(mode="after")
+    def validate_stdio_token(self) -> "Settings":
+        # stdio has no inbound request to forward a credential from, so the
+        # server must hold its own master API key.
+        if self.transport == "stdio" and self.flagsmith_api_token is None:
+            raise ValueError(
+                "FLAGSMITH_API_TOKEN is required when TRANSPORT is 'stdio'"
+            )
+        return self