docs(MCP): Rewrite MCP server page and generate the tool catalogue by khvn26 · Pull Request #7668 · Flagsmith/flagsmith

khvn26 · 2026-06-01T16:24:18Z

Thanks for submitting a PR! Please check the boxes below:

I have read the Contributing Guide.
I have added information to docs/ if required so people know about the feature.
I have filled in the "Changes" section below.
I have filled in the "How did you test this code" section below.

Changes

Contributes to Flagsmith/flagsmith-private#144.

Preview: https://docs-git-docs-rewrite-mcp-server-flagsmith.vercel.app/integrating-with-flagsmith/mcp-server

Rewrites 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://<your-flagsmith-host>/mcp/) URLs.
OAuth (auto-discovered from the MCP URL) 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 and example prompts.

Generates the tool catalogue from the OpenAPI schema instead of hand-maintaining it, so the 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 present in another catalogue.
make generate-docs writes the core catalogue (_mcp-tool-catalogue.md, gated by the existing diff-check). api-tests-with-private-packages derives the enterprise-only catalogue (_mcp-tool-catalogue-enterprise.md) from it (the enterprise tools only exist with private packages installed). The page composes both via MDX imports — hence the .md → .mdx rename.

Note: the page documents URLs/clients ahead of the server going live (doc-led). The install snippets and the Gram deprecation date (currently 30 June 2026) should be confirmed against the live server before/at release — in particular that the documented MCP URL exactly matches the resource in the server's OAuth metadata, or OAuth discovery fails.

How did you test this code?

make -C api generate-docs reproduces _mcp-tool-catalogue.md (36 core tools) byte-identically; make -C api typecheck and ruff pass; docs Prettier passes on the rewritten page and both partials.
Generated the enterprise catalogue with flagsmith-private installed (--exclude the core one) → the 7 enterprise tools; verified both partials are Prettier-stable.
Added unit tests for the management command (tests/unit/api/test_generate_mcp_tool_catalogue.py): default rendering, --exclude, and pipe-escaping — all pass.

vercel · 2026-06-01T16:24:26Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Jun 3, 2026 9:47am

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
flagsmith-frontend-preview	Ignored	Preview	Jun 3, 2026 9:47am
flagsmith-frontend-staging	Ignored	Preview	Jun 3, 2026 9:47am

khvn26 · 2026-06-01T16:25:35Z

Vercel preview of the rewritten page: https://docs-qxrxqbi67-flagsmith.vercel.app/integrating-with-flagsmith/mcp-server

github-actions · 2026-06-01T16:25:55Z

Docker builds report

Image	Build Status	Security report
`ghcr.io/flagsmith/flagsmith-e2e:pr-7668`	Finished ✅	Skipped
`ghcr.io/flagsmith/flagsmith-frontend:pr-7668`	Finished ✅	Results ✅
`ghcr.io/flagsmith/flagsmith-api-test:pr-7668`	Finished ✅	Skipped
`ghcr.io/flagsmith/flagsmith:pr-7668`	Finished ✅	Results ✅
`ghcr.io/flagsmith/flagsmith-private-cloud:pr-7668`	Finished ✅	Results ✅

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://<host>/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

codecov · 2026-06-01T16:30:10Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.52%. Comparing base (1ee9b7b) to head (ef6914b).
⚠️ Report is 14 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7668      +/-   ##
==========================================
- Coverage   98.52%   98.52%   -0.01%     
==========================================
  Files        1444     1446       +2     
  Lines       55083    55030      -53     
==========================================
- Hits        54273    54220      -53     
  Misses        810      810

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-06-01T16:32:11Z

Playwright Test Results (oss - depot-ubuntu-latest-arm-16)

1 passed

Details

1 test across 1 suite
36.6 seconds
5fb9cdd
🔄 Run: #17155 (attempt 1)

3 tests across 3 suites
33.8 seconds
ef6914b
🔄 Run: #17220 (attempt 1)

Playwright Test Results (private-cloud - depot-ubuntu-latest-arm-16)

3 passed

Details

3 tests across 3 suites
35.9 seconds
ef6914b
🔄 Run: #17220 (attempt 1)

github-actions · 2026-06-01T16:33:31Z

Visual Regression

19 screenshots compared. See report for details.
View full report

Zaimwa9

Big big improvement. No specific comments on my side, surprised that codex doesn't have a dedicated command

beep boop

Zaimwa9

Ok, great. Just flagged the CI to make sure it was intentional

emyller

Late non-blocking review.

emyller · 2026-06-16T15:56:02Z

+      - 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
+


Should we add a TODO mentioning #7669?

emyller · 2026-06-16T15:57:13Z

+            "--exclude",
+            type=Path,
+            default=None,
+            help="Path to an existing catalogue whose tools should be omitted.",


Suggested change

help="Path to an existing catalogue whose tools should be omitted.",

help="Path to an existing catalogue which tools should be omitted.",

emyller · 2026-06-16T15:58:55Z

+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)


note: Not a fan of this, seems fragile. Feels like this code should give place to something that should already exist.

Yeah full disclosure I didn't ask Claude to generate prettier-compatible markdown. :/

emyller · 2026-06-16T16:00:53Z

+
+:::caution
+
+The `Api-Key ` prefix is required. The header value should look like `Api-Key ser.abc123…`, not the key on its own.


Suggested change

The `Api-Key ` prefix is required. The header value should look like `Api-Key ser.abc123…`, not the key on its own.

The `Api-Key` prefix is required. The header value should look like `Api-Key ser.abc123…`, not the key on its own.

This isn't incorrect, but leads to a weird rendering:

emyller · 2026-06-16T16:19:24Z

+claude mcp add flagsmith \
+    --env TRANSPORT=stdio \
+    --env FLAGSMITH_API_TOKEN=<your-api-key> \
+    -- uvx --from "git+https://github.com/Flagsmith/flagsmith.git@main#subdirectory=mcp" flagsmith-mcp


q: Would you think this warrants a PyPI package?

Not sure. I can see the devex improvement but I don't imagine stdio will be used a lot to streamline this command. There's no difference security-wise, IMO.

emyller · 2026-06-16T16:20:47Z

+
+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.


q: Did you have a chance to verify it? I realise I did not.

Ah good catch, the tool list result is independent of the upstream API. This needs rewording.

khvn26 requested review from a team as code owners June 1, 2026 16:24

khvn26 requested review from matthewelwell and removed request for a team June 1, 2026 16:24

flagsmith-engineering Bot assigned matthewelwell Jun 1, 2026

vercel Bot deployed to Preview – docs June 1, 2026 16:24 View deployment

github-actions Bot added api Issue related to the REST API docs Documentation updates labels Jun 1, 2026

github-actions Bot added docs Documentation updates and removed docs Documentation updates labels Jun 1, 2026

khvn26 mentioned this pull request Jun 1, 2026

Bundle the Core API OpenAPI schema #7669

Open

khvn26 force-pushed the docs/rewrite-mcp-server branch from 5fb9cdd to 6295a4b Compare June 1, 2026 19:15

vercel Bot deployed to Preview – docs June 1, 2026 19:16 View deployment

github-actions Bot added docs Documentation updates and removed docs Documentation updates labels Jun 1, 2026

Zaimwa9 reviewed Jun 2, 2026

View reviewed changes

docs(MCP): add stdio/uvx option to each client install tab

ef6914b

beep boop

vercel Bot deployed to Preview – docs June 3, 2026 09:47 View deployment

github-actions Bot added docs Documentation updates and removed docs Documentation updates labels Jun 3, 2026

kyle-ssg mentioned this pull request Jun 10, 2026

feat: in app mcp instructions #7438

Merged

4 tasks

khvn26 mentioned this pull request Jun 16, 2026

docs(MCP): Document self-hosting the MCP server #7800

Merged

4 tasks

Zaimwa9 approved these changes Jun 16, 2026

View reviewed changes

Comment thread .github/workflows/api-tests-with-private-packages.yml

khvn26 merged commit 9c8cff0 into main Jun 16, 2026
34 checks passed

khvn26 deleted the docs/rewrite-mcp-server branch June 16, 2026 16:49

flagsmith-engineering Bot mentioned this pull request Jun 16, 2026

chore(main): release 2.242.0 #7791

Merged

emyller reviewed Jun 16, 2026

View reviewed changes

	help="Path to an existing catalogue whose tools should be omitted.",
	help="Path to an existing catalogue which tools should be omitted.",


		:::caution

		The `Api-Key ` prefix is required. The header value should look like `Api-Key ser.abc123…`, not the key on its own.

	The `Api-Key ` prefix is required. The header value should look like `Api-Key ser.abc123…`, not the key on its own.
	The `Api-Key` prefix is required. The header value should look like `Api-Key ser.abc123…`, not the key on its own.

Uh oh!

Conversation

khvn26 commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

How did you test this code?

Uh oh!

vercel Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

khvn26 commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Docker builds report

Uh oh!

codecov Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Playwright Test Results (oss - depot-ubuntu-latest-arm-16)

Details

Playwright Test Results (oss - depot-ubuntu-latest-16)

Details

Playwright Test Results (private-cloud - depot-ubuntu-latest-arm-16)

Details

Playwright Test Results (private-cloud - depot-ubuntu-latest-16)

Details

Playwright Test Results (oss - depot-ubuntu-latest-arm-16)

Details

Playwright Test Results (oss - depot-ubuntu-latest-16)

Details

Playwright Test Results (private-cloud - depot-ubuntu-latest-arm-16)

Details

Playwright Test Results (private-cloud - depot-ubuntu-latest-16)

Details

Playwright Test Results (oss - depot-ubuntu-latest-arm-16)

Details

Playwright Test Results (oss - depot-ubuntu-latest-16)

Details

Playwright Test Results (private-cloud - depot-ubuntu-latest-16)

Details

Playwright Test Results (private-cloud - depot-ubuntu-latest-arm-16)

Details

Uh oh!

github-actions Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Visual Regression

Uh oh!

Zaimwa9 left a comment

Choose a reason for hiding this comment

Uh oh!

Zaimwa9 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

emyller left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

khvn26 Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

khvn26 commented Jun 1, 2026 •

edited

Loading

vercel Bot commented Jun 1, 2026 •

edited

Loading

khvn26 commented Jun 1, 2026 •

edited

Loading

github-actions Bot commented Jun 1, 2026 •

edited

Loading

codecov Bot commented Jun 1, 2026 •

edited

Loading

github-actions Bot commented Jun 1, 2026 •

edited

Loading

github-actions Bot commented Jun 1, 2026 •

edited

Loading

khvn26 Jun 16, 2026 •

edited

Loading