[FEATURE][CONFIG]: Simple endpoint feature flags

[crivetimihai]

[FEATURE][CONFIG]: Enhanced Endpoint Feature Flags

Goal

Add configuration-based feature flags to enable/disable MCP capabilities (tools, resources, prompts, servers, gateways, roots) and additional system endpoints (REST API tools, metrics, version, docs). Features are toggled via environment variables, and the UI/version endpoint shows which features are enabled.

Why Now?

1. Security Hardening: Disable unused capabilities to reduce attack surface
2. Compliance: Some deployments may require certain features disabled
3. Performance: Skip initialization of unused features
4. Customization: Different deployments have different needs
5. Gradual Rollout: Enable experimental features selectively

---

Current State

Existing Flags (implemented):

• MCPGATEWAY_UI_ENABLED - Admin UI interface
• MCPGATEWAY_ADMIN_API_ENABLED - Admin API endpoints
• MCPGATEWAY_BULK_IMPORT_ENABLED - Bulk import endpoint
• MCP_CLIENT_AUTH_ENABLED - JWT auth for MCP clients
• CORS_ENABLED - CORS middleware
• SECURITY_HEADERS_ENABLED - Security headers middleware
• FEDERATION_ENABLED - Gateway federation
• SSE_KEEPALIVE_ENABLED - SSE keepalive events
• PLUGINS_ENABLED - Plugin framework

Missing Flags:

• MCP Capability flags (tools, resources, prompts, servers, gateways, roots)
• System feature flags (version, metrics, docs, redoc)
• REST API tools conversion flag
• Connection tester flag
• Tags router flag

---

📖 User Stories

US-1: Operator - Disable Unused Capabilities

As a platform operator
I want to disable MCP capabilities we don't use
So that the attack surface is minimized

Acceptance Criteria:

Scenario: Disable resources capability
  Given FEATURES_RESOURCES_ENABLED=false
  When a client calls resources/list
  Then a 404 or "capability not available" error should be returned
  And the /resources router should not be mounted

Scenario: Disable prompts capability
  Given FEATURES_PROMPTS_ENABLED=false
  When a client calls prompts/list
  Then a 404 or "capability not available" error should be returned

Scenario: All capabilities enabled by default
  Given no feature flags are set
  Then all MCP capabilities should be enabled
  And all routers should be mounted

Technical Requirements:

• Add FEATURES_TOOLS_ENABLED, FEATURES_RESOURCES_ENABLED, FEATURES_PROMPTS_ENABLED
• Add FEATURES_SERVERS_ENABLED, FEATURES_GATEWAYS_ENABLED, FEATURES_ROOTS_ENABLED
• Conditionally mount routers based on flags
• Update capabilities in initialize response

US-2: Operator - Control System Endpoints

As a platform operator
I want to control which system endpoints are exposed
So that I can hide internal information in production

Acceptance Criteria:

Scenario: Disable metrics endpoint
  Given FEATURES_METRICS_ENABLED=false
  When a client calls GET /metrics
  Then a 404 should be returned

Scenario: Disable OpenAPI docs
  Given FEATURES_DOCS_ENABLED=false
  When a client navigates to /docs
  Then a 404 should be returned
  And /openapi.json should also return 404

Scenario: Disable version endpoint
  Given FEATURES_VERSION_ENABLED=false
  When a client calls GET /version
  Then a 404 should be returned

Technical Requirements:

• Add FEATURES_VERSION_ENABLED, FEATURES_METRICS_ENABLED
• Add FEATURES_DOCS_ENABLED, FEATURES_REDOC_ENABLED
• Conditionally include routers
• Update FastAPI app configuration for docs

US-3: User - See Enabled Features

As a user of the gateway
I want to see which features are enabled
So that I know what capabilities are available

Acceptance Criteria:

Scenario: Version endpoint shows features
  Given various feature flags are configured
  When I call GET /version
  Then the response should include a "features" object
  And each feature should show enabled/disabled status

Scenario: Initialize shows capabilities
  Given FEATURES_RESOURCES_ENABLED=false
  When I send initialize request
  Then the capabilities response should NOT include "resources"

Technical Requirements:

• Add features map to /version response
• Update ServerCapabilities based on flags
• Show feature status in Admin UI

US-4: Developer - Configure REST API Tools

As a developer
I want to enable/disable REST API tool conversion
So that I can control how REST endpoints are exposed

Acceptance Criteria:

Scenario: Disable REST API tools
  Given FEATURES_REST_API_TOOLS_ENABLED=false
  When gateways are loaded
  Then REST endpoints should NOT be converted to tools
  And only native MCP tools should be available

Scenario: Enable REST API tools
  Given FEATURES_REST_API_TOOLS_ENABLED=true
  When a gateway with REST API specification is loaded
  Then REST endpoints should be converted to callable tools

Technical Requirements:

• Add FEATURES_REST_API_TOOLS_ENABLED flag
• Conditionally load REST-to-tool converter
• Skip REST API parsing when disabled

---

🏗 Architecture

Feature Flag Decision Flow

flowchart TD
    A[Application Startup] --> B{Read Feature Flags}
    B --> C{FEATURES_TOOLS_ENABLED?}
    C -->|true| D[Mount /tools router]
    C -->|false| E[Skip /tools router]

    B --> F{FEATURES_DOCS_ENABLED?}
    F -->|true| G[Enable OpenAPI docs]
    F -->|false| H[Disable docs endpoints]

    B --> I{Update Capabilities}
    I --> J[Build ServerCapabilities]
    J --> K[Include only enabled capabilities]

Loading

Feature Flags Configuration

classDiagram
    class FeatureFlags {
        +tools_enabled: bool
        +resources_enabled: bool
        +prompts_enabled: bool
        +servers_enabled: bool
        +gateways_enabled: bool
        +roots_enabled: bool
        +version_enabled: bool
        +metrics_enabled: bool
        +docs_enabled: bool
        +redoc_enabled: bool
        +rest_api_tools_enabled: bool
        +tags_enabled: bool
        +get_enabled_features(): Dict
        +get_capabilities(): ServerCapabilities
    }

Loading

---

📋 Implementation Tasks

Phase 1: MCP Capability Flags

• Add FEATURES_TOOLS_ENABLED (default: true)
• Add FEATURES_RESOURCES_ENABLED (default: true)
• Add FEATURES_PROMPTS_ENABLED (default: true)
• Add FEATURES_SERVERS_ENABLED (default: true)
• Add FEATURES_GATEWAYS_ENABLED (default: true)
• Add FEATURES_ROOTS_ENABLED (default: true)
• Conditionally mount routers in main.py

Phase 2: System Feature Flags

• Add FEATURES_VERSION_ENABLED (default: true)
• Add FEATURES_METRICS_ENABLED (default: true)
• Add FEATURES_DOCS_ENABLED (default: true)
• Add FEATURES_REDOC_ENABLED (default: true)
• Configure FastAPI docs based on flags

Phase 3: Additional Flags

• Add FEATURES_REST_API_TOOLS_ENABLED (default: true)
• Add FEATURES_CONNECTION_TESTER_ENABLED (default: true)
• Add FEATURES_TAGS_ENABLED (default: true)
• Add FEATURES_A2A_AGENTS_ENABLED (default: true)

Phase 4: Capability Updates

• Update ServerCapabilities based on flags
• Update /version to include features map
• Update Admin UI to show enabled features

Phase 5: Documentation

• Document all feature flags in .env.example
• Add feature matrix to documentation
• Document security implications

Phase 6: Testing

• Unit tests for each flag
• Integration tests for disabled endpoints
• Test capability responses

---

⚙️ Configuration Example

# MCP Capability Flags (all default to true)
FEATURES_TOOLS_ENABLED=true
FEATURES_RESOURCES_ENABLED=true
FEATURES_PROMPTS_ENABLED=true
FEATURES_SERVERS_ENABLED=true
FEATURES_GATEWAYS_ENABLED=true
FEATURES_ROOTS_ENABLED=true

# System Feature Flags
FEATURES_VERSION_ENABLED=true
FEATURES_METRICS_ENABLED=true
FEATURES_DOCS_ENABLED=true      # OpenAPI /docs
FEATURES_REDOC_ENABLED=true     # ReDoc /redoc

# Additional Features
FEATURES_REST_API_TOOLS_ENABLED=true
FEATURES_CONNECTION_TESTER_ENABLED=true
FEATURES_TAGS_ENABLED=true
FEATURES_A2A_AGENTS_ENABLED=true

# Security Hardened Configuration Example
# FEATURES_DOCS_ENABLED=false
# FEATURES_REDOC_ENABLED=false
# FEATURES_METRICS_ENABLED=false

---

✅ Success Criteria

• All MCP capability flags implemented
• All system feature flags implemented
• Routers conditionally mounted
• Disabled endpoints return 404
• /version shows features map
• ServerCapabilities reflects enabled features
• Admin UI shows feature status
• Documentation complete

---

🏁 Definition of Done

• All feature flags implemented in config.py
• Conditional router mounting working
• Capability responses updated
• /version endpoint updated
• Admin UI shows features
• Unit tests for all flags
• Integration tests pass
• Code passes make verify
• Documentation updated
• .env.example updated

---

🔗 Related Issues

• Related: [FEATURE][SECURITY]: Add security configuration validation and startup checks #534 (Security config validation)
• Existing flags serve as pattern