🎛️ Feature: Flexible UI Sections for Embedded Contexts

Goal

Enable the Admin UI to be embedded in external applications with configurable section visibility. Operators can hide sections (logout, team selector, prompts, resources) without breaking navigation, and hidden sections won't load unnecessary data.

Why Now?

1. Embedding Requirements: Partners want to embed CF UI in their platforms with customized navigation
2. White-Label Support: Some deployments need minimal UI without team management features
3. Performance: Hidden sections shouldn't trigger data loading (API calls, DB queries)
4. Security: Embedded contexts may need to hide sensitive controls like logout or team switching

📖 User Stories

Scenario: Hide specific sections via environment variable
  Given MCPGATEWAY_UI_HIDE_SECTIONS="prompts,resources,teams"
  When the Admin UI loads
  Then the navigation should not show "Prompts", "Resources", or "Teams" tabs
  And navigating to "#prompts" via URL should redirect to the default section
  And no API calls should be made to /prompts, /resources, or /teams endpoints

Scenario: Hide header items via environment variable
  Given MCPGATEWAY_UI_HIDE_HEADER_ITEMS="logout,team_selector"
  When the Admin UI loads
  Then the header should not show the logout button
  And the header should not show the team selector dropdown
  And the user identity (email) should still be visible

Scenario: Embedded mode enables default hides
  Given MCPGATEWAY_UI_EMBEDDED=true
  And no other hide settings are configured
  When the Admin UI loads
  Then logout and team_selector should be hidden by default
  And all navigation sections should still be visible

Scenario: URL parameter hides additional sections
  Given MCPGATEWAY_UI_HIDE_SECTIONS is not set
  When I navigate to "/admin?ui_hide=prompts,resources"
  Then prompts and resources tabs should be hidden
  And the setting should persist for the session

Scenario: URL parameter combines with environment setting
  Given MCPGATEWAY_UI_HIDE_SECTIONS="teams"
  When I navigate to "/admin?ui_hide=prompts"
  Then both "teams" and "prompts" should be hidden

Scenario: Invalid section names are ignored
  Given I navigate to "/admin?ui_hide=invalid_section,tools"
  When the page loads
  Then "tools" should be hidden
  And no error should occur for "invalid_section"

Scenario: Hidden section data not loaded
  Given MCPGATEWAY_UI_HIDE_SECTIONS="prompts,resources"
  When the Admin UI loads
  Then no XHR requests should be made to /admin/prompts/*
  And no XHR requests should be made to /admin/resources/*
  And the network tab should show fewer requests

Scenario: Navigating to hidden section via hash is blocked
  Given prompts section is hidden
  When I manually change URL to "#prompts"
  Then I should be redirected to the default visible section
  And no prompt data should be loaded

Scenario: Non-admin user doesn't see admin sections
  Given a user without is_admin=true
  And no UI hide settings configured
  When the user accesses the Admin UI
  Then admin-only sections should not be visible
  And this behavior should not change with embedded mode

Scenario: Embedded mode doesn't override permission checks
  Given MCPGATEWAY_UI_EMBEDDED=true
  And a non-admin user
  When the user accesses the Admin UI
  Then admin-only sections should still be hidden
  And embedded mode hides only apply on top of permission checks

🏗 Architecture

Visibility Configuration Model

flowchart TD
    A[Environment Variables] --> D[Visibility Config]
    B[URL Parameters] --> D
    C[User Permissions] --> E[Final Visibility]
    D --> E
    
    subgraph "Environment"
        A1[MCPGATEWAY_UI_EMBEDDED]
        A2[MCPGATEWAY_UI_HIDE_SECTIONS]
        A3[MCPGATEWAY_UI_HIDE_HEADER_ITEMS]
    end
    
    subgraph "Request"
        B1[?ui_hide=prompts,teams]
    end
    
    subgraph "Permission Check"
        C1[is_admin check]
        C2[team membership]
    end

Configuration Hierarchy

1. Built-in defaults (nothing hidden)
2. MCPGATEWAY_UI_EMBEDDED=true applies default embedded hides
3. MCPGATEWAY_UI_HIDE_SECTIONS adds to hidden list
4. MCPGATEWAY_UI_HIDE_HEADER_ITEMS adds to hidden header items
5. ?ui_hide= URL parameter adds more hides
6. Permission checks (is_admin) always enforced on top

Configurable Sections

Configurable Header Items

📋 Implementation Tasks

Phase 1: Configuration Settings

• Add MCPGATEWAY_UI_EMBEDDED: bool = False to config.py
• Add MCPGATEWAY_UI_HIDE_SECTIONS: List[str] = [] to config.py
• Add MCPGATEWAY_UI_HIDE_HEADER_ITEMS: List[str] = [] to config.py
• Add field validators for valid section/header item names
• Document settings in .env.example

Phase 2: Backend Context

• Create get_ui_visibility_config() function in admin.py
• Parse ui_hide query parameter from request
• Merge environment settings with URL overrides
• Pass visibility config to Jinja template context
• Apply embedded mode defaults when enabled

Phase 3: Template Updates

• Update admin.html navigation to check visibility config
• Conditionally render tabs based on hidden_sections
• Update header to check hidden_header_items
• Remove HTMX triggers for hidden sections
• Add default section redirect logic

Phase 4: JavaScript Updates

• Update Alpine.js tab component to exclude hidden sections
• Block hash navigation to hidden sections
• Add redirect to default section when hidden section accessed
• Ensure no API calls for hidden sections

Phase 5: Testing

• Unit tests for visibility config parsing
• Unit tests for config merging logic
• Playwright tests for hidden sections not appearing
• Playwright tests for hash redirect behavior
• Playwright tests for no API calls to hidden sections
• Test embedded mode defaults

⚙️ Configuration Example

# .env.example additions

# Enable embedded mode (hides logout and team_selector by default)
MCPGATEWAY_UI_EMBEDDED=false

# Comma-separated list of sections to hide
# Valid values: servers, gateways, tools, prompts, resources, teams, users, agents, tokens, settings
MCPGATEWAY_UI_HIDE_SECTIONS=

# Comma-separated list of header items to hide
# Valid values: logout, team_selector, user_identity, theme_toggle
MCPGATEWAY_UI_HIDE_HEADER_ITEMS=

# Example: Minimal embedded configuration
# MCPGATEWAY_UI_EMBEDDED=true
# MCPGATEWAY_UI_HIDE_SECTIONS=prompts,resources,teams,users,settings
# MCPGATEWAY_UI_HIDE_HEADER_ITEMS=logout,team_selector

✅ Success Criteria

• Non-admin users never see admin-only sections (existing behavior preserved)
• MCPGATEWAY_UI_EMBEDDED=true hides logout and team_selector by default
• MCPGATEWAY_UI_HIDE_SECTIONS correctly hides specified sections
• MCPGATEWAY_UI_HIDE_HEADER_ITEMS correctly hides specified header items
• Hidden sections are removed from navigation (not just hidden via CSS)
• Hash navigation to hidden sections redirects to default
• Hidden sections do not trigger API calls
• URL parameter ?ui_hide= works and merges with env config
• Default UI unchanged when no config is set
• Playwright tests pass for all visibility scenarios

🏁 Definition of Done

• Configuration settings added to config.py
• Backend visibility config logic implemented
• Templates updated with conditional rendering
• JavaScript updated for hash handling
• Unit tests written and passing
• Playwright tests written and passing
• Code passes make verify
• Settings documented in .env.example
• PR reviewed and approved

📝 Additional Notes

Security Considerations

• Hidden sections are a UI convenience, not a security boundary
• API endpoints still require authentication and authorization
• Hiding "users" section doesn't prevent API access to /admin/users
• For true access control, use RBAC permissions

Performance Impact

• Positive: Fewer API calls when sections hidden
• Positive: Smaller DOM when sections removed
• Neutral: Minimal overhead for visibility config parsing

🔗 Related Issues

• Related to multi-tenant UI customization
• Related to white-label deployment requirements