feat: adds option to disable mcp clients

Author: Pratham-Mishra04

core/bifrost.go

@@ -3738,6 +3738,25 @@ func (bifrost *Bifrost) ReconnectMCPClient(id string) error {
 	return bifrost.MCPManager.ReconnectClient(id)
 }
 
+// DisableMCPClient shuts down an MCP client's connection, health monitor, and tool
+// syncer without removing it. The client entry is kept in a "disabled" state so it
+// can be re-enabled via EnableMCPClient.
+func (bifrost *Bifrost) DisableMCPClient(id string) error {
+	if bifrost.MCPManager == nil {
+		return fmt.Errorf("mcp is not configured in this bifrost instance")
+	}
+	return bifrost.MCPManager.DisableClient(id)
+}
+
+// EnableMCPClient reconnects a previously disabled MCP client and restarts its
+// health monitor and tool syncer.
+func (bifrost *Bifrost) EnableMCPClient(id string) error {
+	if bifrost.MCPManager == nil {
+		return fmt.Errorf("mcp is not configured in this bifrost instance")
+	}
+	return bifrost.MCPManager.EnableClient(id)
+}
+
 // VerifyPerUserOAuthConnection delegates to the MCP manager to verify an MCP
 // server using a temporary access token and discover available tools. The
 // connection is closed after verification. If the MCP manager is not yet

core/mcp/clientmanager.go

@@ -109,6 +109,33 @@ func (m *MCPManager) AddClient(config *schemas.MCPClientConfig) error {
 		return fmt.Errorf("client %s already exists", config.Name)
 	}
 
+	// Disabled clients get a dormant placeholder — no connection, no workers.
+	if config.Disabled {
+		clientState := &schemas.MCPClientState{
+			Name:            config.Name,
+			ExecutionConfig: config,
+			State:           schemas.MCPConnectionStateDisabled,
+			ToolMap:         make(map[string]schemas.ChatTool),
+			ToolNameMapping: make(map[string]string),
+			ConnectionInfo:  &schemas.MCPClientConnectionInfo{Type: config.ConnectionType},
+		}
+		// Persisted tools for per_user_oauth survive restarts in ExecutionConfig.
+		if config.AuthType == schemas.MCPAuthTypePerUserOauth && len(config.DiscoveredTools) > 0 {
+			for toolName, tool := range config.DiscoveredTools {
+				clientState.ToolMap[toolName] = tool
+			}
+			clientState.ToolNameMapping = config.DiscoveredToolNameMapping
+			if config.ConnectionString != nil {
+				url := config.ConnectionString.GetValue()
+				clientState.ConnectionInfo.ConnectionURL = &url
+			}
+		}
+		m.clientMap[config.ID] = clientState
+		m.mu.Unlock()
+		m.logger.Debug("%s MCP client '%s' registered in disabled state", MCPLogPrefix, config.Name)
+		return nil
+	}
+
 	// Create placeholder entry
 	m.clientMap[config.ID] = &schemas.MCPClientState{
 		Name:            config.Name,
@@ -141,10 +168,10 @@ func (m *MCPManager) AddClient(config *schemas.MCPClientConfig) error {
 				}
 				client.ToolNameMapping = config.DiscoveredToolNameMapping
 				client.State = schemas.MCPConnectionStateConnected
-				m.logger.Info("%s Per-user OAuth MCP client '%s' restored with %d tools", MCPLogPrefix, config.Name, len(config.DiscoveredTools))
+				m.logger.Debug("%s Per-user OAuth MCP client '%s' restored with %d tools", MCPLogPrefix, config.Name, len(config.DiscoveredTools))
 			} else {
 				client.State = schemas.MCPConnectionStatePendingTools
-				m.logger.Info("%s Per-user OAuth MCP client '%s' registered (connection deferred to runtime)", MCPLogPrefix, config.Name)
+				m.logger.Debug("%s Per-user OAuth MCP client '%s' registered (connection deferred to runtime)", MCPLogPrefix, config.Name)
 			}
 		}
 		m.mu.Unlock()
@@ -306,6 +333,129 @@ func (m *MCPManager) removeClientUnsafe(id string) error {
 	return nil
 }
 
+// DisableClient shuts down a client's connection, health monitor, and tool syncer
+// without removing it from the manager. The client entry is kept in clientMap with
+// state MCPConnectionStateDisabled so it can be re-enabled later.
+//
+// Parameters:
+//   - id: ID of the client to disable
+//
+// Returns:
+//   - error: Any error that occurred during disable
+func (m *MCPManager) DisableClient(id string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	clientState, ok := m.clientMap[id]
+	if !ok {
+		return fmt.Errorf("client %s not found", id)
+	}
+	if clientState.State == schemas.MCPConnectionStateDisabled {
+		return fmt.Errorf("client %s is already disabled", clientState.ExecutionConfig.Name)
+	}
+
+	m.logger.Debug("%s Disabling MCP client '%s'", MCPLogPrefix, clientState.ExecutionConfig.Name)
+
+	m.healthMonitorManager.StopMonitoring(id)
+	m.toolSyncManager.StopSyncing(id)
+
+	if clientState.CancelFunc != nil {
+		clientState.CancelFunc()
+		clientState.CancelFunc = nil
+	}
+	if clientState.Conn != nil {
+		if err := clientState.Conn.Close(); err != nil {
+			m.logger.Error("%s Failed to close connection for MCP client '%s': %v", MCPLogPrefix, clientState.ExecutionConfig.Name, err)
+		}
+		clientState.Conn = nil
+	}
+
+	// Per-user OAuth clients have no persistent connection — their ToolMap holds
+	// tools discovered via OAuth that can only be recovered by re-running the OAuth
+	// flow. Preserve the ToolMap so re-enabling restores tools immediately.
+	if clientState.ExecutionConfig.AuthType != schemas.MCPAuthTypePerUserOauth {
+		clientState.ToolMap = make(map[string]schemas.ChatTool)
+		clientState.ToolNameMapping = make(map[string]string)
+	}
+	clientState.State = schemas.MCPConnectionStateDisabled
+	clientState.ExecutionConfig.Disabled = true
+	m.logger.Debug("%s MCP client '%s' disabled successfully", MCPLogPrefix, clientState.ExecutionConfig.Name)
+	return nil
+}
+
+// EnableClient re-enables a previously disabled MCP client by reconnecting it
+// and restarting its health monitor and tool syncer.
+//
+// Parameters:
+//   - id: ID of the client to enable
+//
+// Returns:
+//   - error: Any error that occurred during enable or connection
+func (m *MCPManager) EnableClient(id string) error {
+	m.mu.Lock()
+	clientState, ok := m.clientMap[id]
+	if !ok {
+		m.mu.Unlock()
+		return fmt.Errorf("client %s not found", id)
+	}
+	if clientState.State != schemas.MCPConnectionStateDisabled {
+		m.mu.Unlock()
+		return fmt.Errorf("client %s is not disabled (current state: %s)", clientState.ExecutionConfig.Name, clientState.State)
+	}
+
+	clientState.ExecutionConfig.Disabled = false
+	configCopy := clientState.ExecutionConfig
+	m.mu.Unlock()
+
+	m.logger.Debug("%s Enabling MCP client '%s'", MCPLogPrefix, configCopy.Name)
+
+	// Per-user OAuth clients have no persistent connection — auth is per-request.
+	// Mirror the AddClient early-return path: just restore the runtime state based
+	// on whether tools were previously discovered.
+	if configCopy.AuthType == schemas.MCPAuthTypePerUserOauth {
+		m.mu.Lock()
+		if cs, exists := m.clientMap[id]; exists {
+			if len(cs.ToolMap) > 0 {
+				cs.State = schemas.MCPConnectionStateConnected
+			} else {
+				cs.State = schemas.MCPConnectionStatePendingTools
+			}
+		}
+		m.mu.Unlock()
+		m.logger.Debug("%s Per-user OAuth MCP client '%s' enabled (no persistent connection)", MCPLogPrefix, configCopy.Name)
+		return nil
+	}
+
+	// Guard against concurrent reconnects for the same client from any caller
+	// (health monitor, manual API call, etc.). LoadOrStore is atomic — whichever
+	// caller arrives second gets the "already in progress" error immediately.
+	if _, alreadyReconnecting := m.reconnectingClients.LoadOrStore(id, true); alreadyReconnecting {
+		return fmt.Errorf("reconnect already in progress for this client")
+	}
+	defer m.reconnectingClients.Delete(id)
+
+	if err := m.connectToMCPClient(configCopy); err != nil {
+		// Connection failed — leave the entry as Disconnected so the health monitor can recover it
+		m.mu.Lock()
+		if cs, exists := m.clientMap[id]; exists {
+			cs.State = schemas.MCPConnectionStateDisconnected
+		}
+		m.mu.Unlock()
+
+		isPingAvailable := true
+		if configCopy.IsPingAvailable != nil {
+			isPingAvailable = *configCopy.IsPingAvailable
+		}
+		monitor := NewClientHealthMonitor(m, id, DefaultHealthCheckInterval, isPingAvailable, m.logger)
+		m.healthMonitorManager.StartMonitoring(monitor)
+
+		return fmt.Errorf("failed to connect MCP client '%s': %w", configCopy.Name, err)
+	}
+
+	m.logger.Debug("%s MCP client '%s' enabled successfully", MCPLogPrefix, configCopy.Name)
+	return nil
+}
+
 // UpdateClient updates an existing MCP client's configuration and refreshes its tool list.
 // It updates the client's execution config with new settings and retrieves updated tools
 // from the MCP server if the client is connected.
@@ -371,6 +521,7 @@ func (m *MCPManager) UpdateClient(id string, updatedConfig *schemas.MCPClientCon
 		IsPingAvailable:       updatedConfig.IsPingAvailable,
 		ToolSyncInterval:      updatedConfig.ToolSyncInterval,
 		AllowOnAllVirtualKeys: updatedConfig.AllowOnAllVirtualKeys,
+		Disabled:              updatedConfig.Disabled,
 	}
 
 	// Atomically replace the config pointer

core/mcp/healthmonitor.go

@@ -145,9 +145,11 @@ func (chm *ClientHealthMonitor) performHealthCheck() {
 	// don't race with removeClientUnsafe zeroing it under the write lock.
 	chm.manager.mu.RLock()
 	clientState, exists := chm.manager.clientMap[chm.clientID]
+	var isDisabled bool
 	var conn *client.Client
 	if exists && clientState != nil {
 		conn = clientState.Conn
+		isDisabled = clientState.State == schemas.MCPConnectionStateDisabled
 	}
 	chm.manager.mu.RUnlock()
 
@@ -156,6 +158,13 @@ func (chm *ClientHealthMonitor) performHealthCheck() {
 		return
 	}
 
+	// Do not health-check intentionally disabled clients
+	// Health monitoring is already stopped for disabled clients. This is just a sanity check.
+	if isDisabled {
+		chm.Stop()
+		return
+	}
+
 	var err error
 	if conn == nil {
 		// No active connection — treat as a health check failure
@@ -210,6 +219,17 @@ func (chm *ClientHealthMonitor) attemptReconnect() {
 
 	chm.logger.Debug("%s Attempting to reconnect MCP client %s...", MCPLogPrefix, chm.clientID)
 
+	// Do not attempt reconnect if the client has been intentionally disabled
+	// Health monitoring is already stopped for disabled clients. This is just a sanity check.
+	chm.manager.mu.RLock()
+	clientState, exists := chm.manager.clientMap[chm.clientID]
+	isDisabled := exists && clientState != nil && clientState.State == schemas.MCPConnectionStateDisabled
+	chm.manager.mu.RUnlock()
+	if isDisabled {
+		chm.logger.Debug("%s Skipping reconnect for disabled MCP client %s", MCPLogPrefix, chm.clientID)
+		return
+	}
+
 	if err := chm.manager.ReconnectClient(chm.clientID); err != nil {
 		chm.logger.Warn("%s Failed to reconnect MCP client %s: %v", MCPLogPrefix, chm.clientID, err)
 		return

core/mcp/interface.go

@@ -62,6 +62,12 @@ type MCPManagerInterface interface {
 	// ReconnectClient reconnects an MCP client by ID
 	ReconnectClient(id string) error
 
+	// DisableClient shuts down a client's connection and workers without removing it
+	DisableClient(id string) error
+
+	// EnableClient reconnects a disabled client and restarts its workers
+	EnableClient(id string) error
+
 	// VerifyPerUserOAuthConnection creates a temporary MCP connection using a
 	// test access token to verify connectivity and discover tools. The connection
 	// is closed after verification.

core/mcp/utils.go

@@ -79,6 +79,12 @@ func (m *MCPManager) GetToolPerClient(ctx context.Context) map[string][]schemas.
 
 		m.logger.Debug("%s Evaluating client %s (ID: %s) for tools", MCPLogPrefix, clientName, clientID)
 
+		// Skip intentionally disabled clients
+		if client.State == schemas.MCPConnectionStateDisabled {
+			m.logger.Debug("%s Skipping disabled MCP client %s", MCPLogPrefix, clientName)
+			continue
+		}
+
 		// Apply client filtering logic - check both ID and Name for compatibility
 		if !shouldIncludeClient(clientName, includeClients, m.logger) {
 			m.logger.Debug("%s Skipping MCP client %s: not in include clients list", MCPLogPrefix, clientName)

core/schemas/mcp.go

@@ -175,6 +175,7 @@ type MCPClientConfig struct {
 	IsPingAvailable       *bool              `json:"is_ping_available,omitempty"`  // Whether the MCP server supports ping for health checks (nil/true = ping; false = listTools). Defaults to true.
 	ToolSyncInterval      time.Duration      `json:"tool_sync_interval,omitempty"` // Per-client override for tool sync interval (0 = use global, negative = disabled)
 	ToolPricing           map[string]float64 `json:"tool_pricing,omitempty"`       // Tool pricing for each tool (cost per execution)
+	Disabled              bool               `json:"disabled"`                     // Whether the client is intentionally disabled (stops connection and workers)
 	ConfigHash            string             `json:"-"`                            // Config hash for reconciliation (not serialized)
 	AllowOnAllVirtualKeys bool               `json:"allow_on_all_virtual_keys"`    // Whether to allow the MCP client to run on all virtual keys
 
@@ -360,6 +361,7 @@ const (
 	MCPConnectionStateDisconnected MCPConnectionState = "disconnected"  // Client is not connected
 	MCPConnectionStateError        MCPConnectionState = "error"         // Client is in an error state, and cannot be used
 	MCPConnectionStatePendingTools MCPConnectionState = "pending_tools" // Connected but tools not yet populated
+	MCPConnectionStateDisabled     MCPConnectionState = "disabled"      // Client is intentionally disabled by the user
 )
 
 // MCPClientState represents a connected MCP client with its configuration and tools.

docs/mcp/connecting-to-servers.mdx

@@ -921,6 +921,44 @@ if err != nil {
 
 ---
 
+## Disabling and Re-enabling Clients
+
+You can temporarily disable an MCP client without removing it. When disabled, Bifrost shuts down the client's connection, health monitor, and tool syncer. The client entry is preserved and its tools are invisible to inference requests until it is re-enabled.
+
+<Tabs>
+<Tab title="Web UI">
+
+Use the **Enabled** toggle in the MCP Server Catalog table to disable or re-enable a client with a single click. The toggle shows a loading spinner while the API call is in flight and automatically reflects the updated state.
+
+![MCP client enable/disable toggle in the server catalog table](/images/placeholder-mcp-disable-toggle.png)
+
+</Tab>
+<Tab title="Gateway API">
+
+```bash
+# Disable a client
+curl -X PUT http://localhost:8080/api/mcp/client/{id} \
+  -H "Content-Type: application/json" \
+  -d '{"disabled": true}'
+
+# Re-enable a client (reconnects automatically)
+curl -X PUT http://localhost:8080/api/mcp/client/{id} \
+  -H "Content-Type: application/json" \
+  -d '{"disabled": false}'
+```
+
+</Tab>
+<Tab title="config.json">
+
+The `disabled` field is a runtime API state and **cannot** be set in `config.json`. Clients defined in `config.json` always start enabled. Use the Web UI or Gateway API to disable a client after it has been created.
+
+</Tab>
+</Tabs>
+
+The `disabled` state persists across restarts — a disabled client is loaded into memory on boot but its connection is not established until it is explicitly re-enabled. Config changes (name, tools, headers) sent in the same PUT request as a `disabled` change are applied before the connection is shut down or re-established.
+
+---
+
 ## Naming Conventions
 
 MCP client names have specific requirements:

docs/openapi/paths/management/mcp.yaml

@@ -126,6 +126,7 @@ client-by-id:
       Updates an existing MCP client's configuration.
       Unlike client creation, tool_pricing can be included to set per-tool execution costs since tools are already fetched.
       Optionally provide vk_configs to manage which virtual keys have access to this MCP server and with which tools. When provided, this fully replaces all existing VK assignments in a single atomic transaction.
+      Set disabled: true to shut down the client's connection and workers without removing it. Set disabled: false to reconnect a previously disabled client.
     tags:
       - MCP
     parameters:

docs/openapi/schemas/management/mcp.yaml

@@ -17,8 +17,14 @@ MCPConnectionType:
 
 MCPConnectionState:
   type: string
-  enum: [connected, disconnected, error]
-  description: Connection state of an MCP client
+  enum: [connected, disconnected, error, pending_tools, disabled]
+  description: |
+    Connection state of an MCP client:
+    - connected: Client is connected and ready to use
+    - disconnected: Client is not connected (will be auto-recovered by health monitor)
+    - error: Client is in an unrecoverable error state
+    - pending_tools: Connected but tools not yet populated (per-user OAuth clients)
+    - disabled: Client has been intentionally disabled; no connection or workers are active
 
 MCPStdioConfig:
   type: object
@@ -242,6 +248,13 @@ MCPClientUpdateRequest:
         When true, this MCP client's tools are accessible to all virtual keys without requiring
         explicit per-key assignment. All tools are allowed by default. If a virtual key has an
         explicit MCP config for this client, that config takes precedence and overrides this behaviour.
+    disabled:
+      type: boolean
+      default: false
+      description: |
+        When true, the client's connection, health monitor, and tool syncer are shut down.
+        The client entry is preserved so it can be re-enabled later by sending disabled: false.
+        Disabled clients do not expose tools to inference requests.
     vk_configs:
       type: array
       items:
@@ -342,6 +355,12 @@ MCPClientConfig:
         When true, this MCP client's tools are accessible to all virtual keys without requiring
         explicit per-key assignment. All tools are allowed by default. If a virtual key has an
         explicit MCP config for this client, that config takes precedence and overrides this behaviour.
+    disabled:
+      type: boolean
+      default: false
+      description: |
+        Whether the client is intentionally disabled.
+        When true, the client has no active connection or workers and its tools are not available for inference.
 
 ChatToolFunction:
   type: object