Skip to content

feat(ui): flexible admin UI sections for embedded contexts#2869

Merged
crivetimihai merged 10 commits intomainfrom
ui-feature-flags
Feb 16, 2026
Merged

feat(ui): flexible admin UI sections for embedded contexts#2869
crivetimihai merged 10 commits intomainfrom
ui-feature-flags

Conversation

@crivetimihai
Copy link
Copy Markdown
Member

@crivetimihai crivetimihai commented Feb 12, 2026 •
edited by madhav165
Loading

Summary

Closes #2075

Adds flexible Admin UI visibility controls for embedded contexts, allowing specific UI sections and header controls to be hidden without triggering backend data loads. Hidden/
invalid hash navigation is redirected to the first available visible tab.

Configuration

New env vars:

  • MCPGATEWAY_UI_EMBEDDED (bool): Enables embedded UI mode (hides logout + team_selector by default).
  • MCPGATEWAY_UI_HIDE_SECTIONS (CSV/JSON list): Hide UI sections.
    • Valid: servers, gateways, tools, prompts, resources, teams, users, agents, tokens, settings
    • Aliases supported: catalog/virtual_servers -> servers, a2a/a2a-agents/grpc-services -> agents, api_tokens -> tokens, llm-settings -> settings
  • MCPGATEWAY_UI_HIDE_HEADER_ITEMS (CSV/JSON list): Hide header items.
    • Valid: logout, team_selector, user_identity, theme_toggle

Per-request override:

  • GET /admin/?ui_hide=prompts,resources,teams
  • Query override is persisted to a session cookie (mcpgateway_ui_hide_sections); clear by visiting /admin/?ui_hide=.

What Changed

  • mcpgateway/config.py
    • Adds embedded/visibility settings with CSV/JSON parsing, aliasing, validation, and dedupe.
  • mcpgateway/admin.py
    • Computes effective hidden sections/header items/tabs from env + embedded defaults + query param + cookie.
    • Skips service list calls (and team lookups where possible) for hidden sections so hidden UI does not load data.
    • Persists ui_hide overrides in an HttpOnly cookie (honors secure/samesite settings).
  • mcpgateway/templates/admin.html
    • Conditionally renders sidebar links, panels, and header items based on hidden values.
    • Exposes UI_HIDDEN_SECTIONS, UI_HIDDEN_HEADER_ITEMS, UI_HIDDEN_TABS globals for client-side nav.
  • mcpgateway/static/admin.js
    • Hidden-aware tab resolution: redirects hidden/invalid hashes to a visible default tab and blocks navigation to hidden tabs.
    • Prevents duplicate loads from overlapping click/hashchange handlers.
    • Skips tools loading and section reload logic when sections are hidden.
  • Packaging/docs
    • Updates charts/mcp-stack/values.yaml, charts/mcp-stack/values.schema.json, charts/mcp-stack/README.md
    • Updates docker-compose.yml
    • Updates docs/docs/config.schema.json and docs/docs/manage/configuration.md

@crivetimihai crivetimihai self-assigned this Feb 12, 2026
@crivetimihai crivetimihai added ica ICA related issues ui User Interface labels Feb 12, 2026
@crivetimihai
feat(ui): flexible admin UI sections for embedded contexts
e1473f9 
Add env controls to hide UI sections/header items (including embedded mode defaults).

Support per-request ?ui_hide= overrides persisted via cookie and prevent hidden sections from loading data.

Update Helm values/schema, docker-compose, docs, and add unit + JS tests.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@crivetimihai
fix(ui): restore default tab fallback
67626d7 
Prefer the Overview tab when available and fall back to Gateways for minimal DOM states.

Align JS tab tests with the restored default tab behavior.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@crivetimihai
fix(ui): review fixes for admin UI section visibility
2db3c72 
Deduplicate UI_HIDABLE_SECTIONS, UI_HIDABLE_HEADER_ITEMS, and
UI_HIDE_SECTION_ALIASES constants — define once in config.py, import
in admin.py.

Harden normalizeTabName() against CSS selector injection by
restricting to [a-z0-9-] characters.

Add max_age (30 days) to the ui_hide_sections cookie so preferences
persist across browser sessions.

Filter global search results to exclude hidden sections.

Expand JS test coverage: normalizeTabName edge cases, admin-only tab
blocking, idempotency guard, getDefaultTabName priority,
isTabAvailable, getUiHiddenSections/Tabs normalization, and global
search filtering.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@crivetimihai
test(ui): add comprehensive test coverage for admin UI section visibi…
ff51f9e 
…lity

Cover _normalize_ui_hide_values, cookie set/delete behavior,
section-aware data loading, config validators, isTabHidden,
and resolveTabForNavigation.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@crivetimihai
fix(config): use NoDecode class instead of instance for env parsing
0eb7f22 
NoDecode() (instance) in Annotated metadata is not found by
pydantic-settings' `NoDecode in field.metadata` check, causing
json.loads to be called on raw CSV strings. Use NoDecode (class)
which matches correctly. Also adds ADR-040 and admin UI
customization guide.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@crivetimihai crivetimihai marked this pull request as ready for review February 16, 2026 12:40
@gcgoncalves
Copy link
Copy Markdown
Collaborator

gcgoncalves commented Feb 16, 2026

Some considerations on testing the changes:

  1. Some items are not hideable. All items listed on the issue are, but some are not listed on the issue would make sense to hide as well (e.g.: roots, mcp-registry, llm-chat)
  2. The flags work well on combination (url + env)
  3. URL flags are not persisted, though.
  4. That said, if a user deletes the session storage value and then switches teams, the hidden tabs are back in display.
  5. Accessing a hidden tab does render an empty panel. 👍
  6. The other two flags (MCPGATEWAY_UI_EMBEDDED and MCPGATEWAY_UI_HIDE_HEADER_ITEMS) work as expected.

@crivetimihai
Fixes
6fbcd36 
Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@crivetimihai
fix(ui): expand admin section hiding coverage
289f1ac 
Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@crivetimihai
test(metrics): stabilize db engine detection setup test
1559441 
Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@crivetimihai
fix(playwright): stabilize admin ui tab and search flows
fdceb06 
Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@crivetimihai
Fixes
a02b685 
Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@crivetimihai crivetimihai added this to the Release 1.0.0-RC1 milestone Feb 16, 2026
@crivetimihai crivetimihai merged commit 6387307 into main Feb 16, 2026
54 checks passed
@crivetimihai crivetimihai deleted the ui-feature-flags branch February 16, 2026 19:13
@crivetimihai
Copy link
Copy Markdown
Member Author

crivetimihai commented Feb 17, 2026 •
edited
Loading

More items can be hidden now:

# Valid values: overview, servers, gateways, tools, prompts, resources, roots, mcp-registry, metrics, plugins, export-import, logs, version-info, maintenance, teams, users, agents, tokens, settings

@IuliaGaitan
Copy link
Copy Markdown
Collaborator

IuliaGaitan commented Feb 17, 2026

Tested on my local environment.

Test Case # Description Example Hidden Items Expected Behavior Steps to Reproduce Status
🟦 SINGLE‑ITEM HIDDEN CASES
TC01 Hide Agents agents Hides Agents section Set env var to agents 🟢
TC02 Hide Export/Import export-import Hides Export/Import Set env var to export-import 🟢
TC03 Hide Gateways gateways Hides Gateways section Set env var to gateways 🟢
TC04 Hide Logs logs Hides Logs Set env var to logs 🟢
TC05 Hide Maintenance maintenance Hides Maintenance Set env var to maintenance 🟢
TC06 Hide MCP Registry mcp-registry Hides MCP Registry Set env var to mcp-registry 🟢
TC07 Hide Metrics metrics Hides Metrics Set env var to metrics 🟢
TC08 Hide Overview overview Hides Overview section Set env var to overview 🟢
TC09 Hide Plugins plugins Hides Plugins Set env var to plugins 🟢
TC10 Hide Prompts prompts Hides Prompts Set env var to prompts 🟢
TC11 Hide Resources resources Hides Resources Set env var to resources 🟢
TC12 Hide Roots roots Hides Roots Set env var to roots 🟢
TC13 Hide Servers servers Hides Servers section Set env var to servers 🟢
TC14 Hide Settings llm-settings Hides Settings Set env var to llm-settings 🟢
TC15 Hide Teams teams Hides Teams Set env var to teams 🟢
TC16 Hide Tokens tokens Hides Tokens Set env var to tokens 🟢
TC17 Hide Tools tools Hides Tools section Set env var to tools 🟢
TC18 Hide Users users Hides Users Set env var to users 🟢
TC19 Hide Version Info version-info Hides Version Info Set env var to version-info 🟢
🟧 COMBINATION CASES
TC20 Hide all except one all except roots All except roots hidden Set env var to full list minus roots 🟢
TC21 Hide two items servers, gateways Both hidden Set env var to servers,gateways 🟢
TC22 Hide multiple items logs, metrics, plugins All hidden Set env var to the list 🟢
TC23 Hide many items metrics, logs, plugins, tools, prompts, users, teams All hidden Set env var to large set 🟢
🟥 EDGE CASES
TC24 Empty value (none) Nothing hidden Set env var empty 🟢
TC25 Duplicate entries agents, agents, agents Hides Agents section Set env var with duplicates 🟢
TC26 Wrong capitalization LOGS Hides Logs section Set env var with uppercase 🟢
TC27 Leading comma ,servers Hides Virtual Servers section Set env var starting with comma 🟢
TC28 Trailing comma roots, Hides Roots section Set env var ending with comma 🟢
TC29 Wrong delimiter servers;logs Invalid - no section hidden Use semicolon delimiter 🟢
TC30 Unknown section xyz, ser Invalid- no section hidden Set env var with invalid item 🟢
TC31 Wildcard used * Invalid- no section hidden Set env var to "*" 🟢
TC32 Whitespace only " " Invalid- no section hidden Set env var to spaces 🟢
TC33 Invalid type 12345 Invalid- no section hidden Set env var to number 🟢
🟩 ALL‑ITEMS CASE
TC34 Hide every valid item all valid values Entire UI hidden Set env var to full list 🟢

TC20 export MCPGATEWAY_UI_HIDE_SECTIONS="metrics, logs, plugins, tools, prompts, users, teams,gateways,servers,resources,mcp-registry,agents,llm-settings,tokens,export-import,version-info,maintenance"

image

TC34 export MCPGATEWAY_UI_HIDE_SECTIONS="metrics, logs, plugins, tools, prompts, users, teams,gateways,servers,resources,mcp-registry,agents,llm-settings,tokens,export-import,version-info,maintenance,roots,overview"
image

vishu-bh pushed a commit that referenced this pull request Feb 18, 2026
@crivetimihai @vishu-bh
feat(ui): flexible admin UI sections for embedded contexts (#2869)
1f54cab 
* feat(ui): flexible admin UI sections for embedded contexts

Add env controls to hide UI sections/header items (including embedded mode defaults).

Support per-request ?ui_hide= overrides persisted via cookie and prevent hidden sections from loading data.

Update Helm values/schema, docker-compose, docs, and add unit + JS tests.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(ui): restore default tab fallback

Prefer the Overview tab when available and fall back to Gateways for minimal DOM states.

Align JS tab tests with the restored default tab behavior.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(ui): review fixes for admin UI section visibility

Deduplicate UI_HIDABLE_SECTIONS, UI_HIDABLE_HEADER_ITEMS, and
UI_HIDE_SECTION_ALIASES constants — define once in config.py, import
in admin.py.

Harden normalizeTabName() against CSS selector injection by
restricting to [a-z0-9-] characters.

Add max_age (30 days) to the ui_hide_sections cookie so preferences
persist across browser sessions.

Filter global search results to exclude hidden sections.

Expand JS test coverage: normalizeTabName edge cases, admin-only tab
blocking, idempotency guard, getDefaultTabName priority,
isTabAvailable, getUiHiddenSections/Tabs normalization, and global
search filtering.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* test(ui): add comprehensive test coverage for admin UI section visibility

Cover _normalize_ui_hide_values, cookie set/delete behavior,
section-aware data loading, config validators, isTabHidden,
and resolveTabForNavigation.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(config): use NoDecode class instead of instance for env parsing

NoDecode() (instance) in Annotated metadata is not found by
pydantic-settings' `NoDecode in field.metadata` check, causing
json.loads to be called on raw CSV strings. Use NoDecode (class)
which matches correctly. Also adds ADR-040 and admin UI
customization guide.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* Fixes

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(ui): expand admin section hiding coverage

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* test(metrics): stabilize db engine detection setup test

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(playwright): stabilize admin ui tab and search flows

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* Fixes

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

---------

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
Signed-off-by: Vishu Bhatnagar <vishu.bhatnagar@ibm.com>
cafalchio pushed a commit that referenced this pull request Feb 26, 2026
@crivetimihai
feat(ui): flexible admin UI sections for embedded contexts (#2869)
de2f3f2 
* feat(ui): flexible admin UI sections for embedded contexts

Add env controls to hide UI sections/header items (including embedded mode defaults).

Support per-request ?ui_hide= overrides persisted via cookie and prevent hidden sections from loading data.

Update Helm values/schema, docker-compose, docs, and add unit + JS tests.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(ui): restore default tab fallback

Prefer the Overview tab when available and fall back to Gateways for minimal DOM states.

Align JS tab tests with the restored default tab behavior.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(ui): review fixes for admin UI section visibility

Deduplicate UI_HIDABLE_SECTIONS, UI_HIDABLE_HEADER_ITEMS, and
UI_HIDE_SECTION_ALIASES constants — define once in config.py, import
in admin.py.

Harden normalizeTabName() against CSS selector injection by
restricting to [a-z0-9-] characters.

Add max_age (30 days) to the ui_hide_sections cookie so preferences
persist across browser sessions.

Filter global search results to exclude hidden sections.

Expand JS test coverage: normalizeTabName edge cases, admin-only tab
blocking, idempotency guard, getDefaultTabName priority,
isTabAvailable, getUiHiddenSections/Tabs normalization, and global
search filtering.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* test(ui): add comprehensive test coverage for admin UI section visibility

Cover _normalize_ui_hide_values, cookie set/delete behavior,
section-aware data loading, config validators, isTabHidden,
and resolveTabForNavigation.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(config): use NoDecode class instead of instance for env parsing

NoDecode() (instance) in Annotated metadata is not found by
pydantic-settings' `NoDecode in field.metadata` check, causing
json.loads to be called on raw CSV strings. Use NoDecode (class)
which matches correctly. Also adds ADR-040 and admin UI
customization guide.

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* Fixes

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(ui): expand admin section hiding coverage

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* test(metrics): stabilize db engine detection setup test

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* fix(playwright): stabilize admin ui tab and search flows

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

* Fixes

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>

---------

Signed-off-by: Mihai Criveti <crivetimihai@gmail.com>
@madhav165 madhav165 mentioned this pull request Mar 4, 2026
Open
3 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@kevalmahajan kevalmahajan Awaiting requested review from kevalmahajan kevalmahajan is a code owner

@madhav165 madhav165 Awaiting requested review from madhav165 madhav165 is a code owner

@jonpspri jonpspri Awaiting requested review from jonpspri

@gcgoncalves gcgoncalves Awaiting requested review from gcgoncalves

Assignees

@crivetimihai crivetimihai

Labels

ica ICA related issues ui User Interface

Projects

None yet

Milestone

Release 1.0.0-RC1

Development

Successfully merging this pull request may close these issues.

[FEATURE][UI]: Flexible UI sections for embedded contexts

3 participants

@crivetimihai @gcgoncalves @IuliaGaitan