feat: add configurable MCP health check method with ping fallback (#1433)

## Add configurable MCP health check method

This PR adds a new `is_ping_available` configuration option for MCP clients, allowing users to specify whether a server supports the lightweight ping method for health checks. When disabled, Bifrost will use the heavier but more universally supported `listTools` method instead.

## Changes

- Added `is_ping_available` boolean field to MCP client configuration (defaults to true)
- Modified health monitor to use either ping or listTools based on this setting
- Added database migration to support the new column
- Updated UI to include a toggle for this setting in MCP client forms
- Added example HTTP server without ping support to demonstrate the feature
- Updated documentation with details on health check methods and configuration options

## Type of change

- [x] Feature
- [x] Documentation

## Affected areas

- [x] Core (Go)
- [x] Transports (HTTP)
- [x] UI (Next.js)
- [x] Docs

## How to test

1. Start Bifrost and add a new MCP server with `is_ping_available: false`
2. Run the example no-ping server:
```sh
cd examples/mcps/http-no-ping-server
go run main.go
```
3. Connect to the server in Bifrost and verify health checks work despite ping being unavailable
4. Toggle the setting in the UI and observe health check behavior changes

## Screenshots/Recordings

![Ping Available Toggle](/media/ui-mcp-ping-available.png)

## Breaking changes

- [x] No

## Related issues

Addresses the need for health checks with MCP servers that don't implement the optional ping method.

## Security considerations

No security implications - this is a configuration option for health check behavior.

## Checklist

- [x] I added/updated tests where appropriate
- [x] I updated documentation where needed
- [x] I verified builds succeed (Go and UI)

Author: akshaydeo

core/changelog.md

@@ -1,3 +1,4 @@
+- feat: add is_ping_available configuration for MCP health checks
 - fix: allow flat $defs and propertyOrdering in jsonschema and forward it to Gemini
 - feat: adds beta feature for Anthropic
   - deferLoading
@@ -6,6 +7,6 @@
   - inputExamples
   - add IsError to tool_result content
   - add "none" option to ToolChoice.Type
-  
+
 - fix: implement structured output handling for Anthropic models on Vertex where the beta structured-output header is unsupported
 - fix: duplicate error when adding first MCP server

core/mcp/clientmanager.go

@@ -189,16 +189,29 @@ func (m *MCPManager) EditClient(id string, updatedConfig schemas.MCPClientConfig
 		return fmt.Errorf("invalid MCP client configuration: %w", err)
 	}
 
+	// Check if is_ping_available changed
+	isPingAvailableChanged := client.ExecutionConfig.IsPingAvailable != updatedConfig.IsPingAvailable
+
 	// Update the client's execution config with new tool filters
 	config := client.ExecutionConfig
 	config.Name = updatedConfig.Name
 	config.IsCodeModeClient = updatedConfig.IsCodeModeClient
 	config.Headers = updatedConfig.Headers
 	config.ToolsToExecute = updatedConfig.ToolsToExecute
 	config.ToolsToAutoExecute = updatedConfig.ToolsToAutoExecute
+	config.IsPingAvailable = updatedConfig.IsPingAvailable
 
 	// Store the updated config
 	client.ExecutionConfig = config
+
+	// If is_ping_available changed, update the health monitor
+	if isPingAvailableChanged {
+		// Stop and restart the health monitor with the new is_ping_available setting
+		m.healthMonitorManager.StopMonitoring(id)
+		monitor := NewClientHealthMonitor(m, id, DefaultHealthCheckInterval, config.IsPingAvailable)
+		m.healthMonitorManager.StartMonitoring(monitor)
+	}
+
 	return nil
 }
 
@@ -445,7 +458,7 @@ func (m *MCPManager) connectToMCPClient(config schemas.MCPClientConfig) error {
 	}
 
 	// Start health monitoring for the client
-	monitor := NewClientHealthMonitor(m, config.ID, DefaultHealthCheckInterval)
+	monitor := NewClientHealthMonitor(m, config.ID, DefaultHealthCheckInterval, config.IsPingAvailable)
 	m.healthMonitorManager.StartMonitoring(monitor)
 
 	return nil

core/mcp/health_monitor.go

@@ -6,6 +6,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/maximhq/bifrost/core/schemas"
 )
 
@@ -29,13 +30,15 @@ type ClientHealthMonitor struct {
 	cancel                 context.CancelFunc
 	isMonitoring           bool
 	consecutiveFailures    int
+	isPingAvailable        bool // Whether the MCP server supports ping for health checks
 }
 
 // NewClientHealthMonitor creates a new health monitor for an MCP client
 func NewClientHealthMonitor(
 	manager *MCPManager,
 	clientID string,
 	interval time.Duration,
+	isPingAvailable bool,
 ) *ClientHealthMonitor {
 	if interval == 0 {
 		interval = DefaultHealthCheckInterval
@@ -49,6 +52,7 @@ func NewClientHealthMonitor(
 		maxConsecutiveFailures: MaxConsecutiveFailures,
 		isMonitoring:           false,
 		consecutiveFailures:    0,
+		isPingAvailable:        isPingAvailable,
 	}
 }
 
@@ -119,11 +123,26 @@ func (chm *ClientHealthMonitor) performHealthCheck() {
 		return
 	}
 
-	// Perform ping with timeout
+	// Perform health check with timeout
 	ctx, cancel := context.WithTimeout(context.Background(), chm.timeout)
 	defer cancel()
 
-	err := clientState.Conn.Ping(ctx)
+	var err error
+	if chm.isPingAvailable {
+		// Use lightweight ping for health check
+		err = clientState.Conn.Ping(ctx)
+	} else {
+		// Fall back to listTools for servers that don't support ping
+		listRequest := mcp.ListToolsRequest{
+			PaginatedRequest: mcp.PaginatedRequest{
+				Request: mcp.Request{
+					Method: string(mcp.MethodToolsList),
+				},
+			},
+		}
+		_, err = clientState.Conn.ListTools(ctx, listRequest)
+	}
+
 	if err != nil {
 		chm.incrementFailures()
 

core/schemas/mcp.go

@@ -67,7 +67,8 @@ type MCPClientConfig struct {
 	// - nil/omitted => treated as [] (no tools)
 	// - ["tool1", "tool2"] => auto-execute only the specified tools
 	// Note: If a tool is in ToolsToAutoExecute but not in ToolsToExecute, it will be skipped.
-	ConfigHash string `json:"-"` // Config hash for reconciliation (not serialized)
+	IsPingAvailable bool   `json:"is_ping_available"` // Whether the MCP server supports ping for health checks (default: true). If false, uses listTools for health checks.
+	ConfigHash      string `json:"-"`                 // Config hash for reconciliation (not serialized)
 }
 
 // NewMCPClientConfigFromMap creates a new MCP client config from a map[string]any.

docs/mcp/connecting-to-servers.mdx

@@ -223,6 +223,7 @@ Configure MCP clients in your `config.json`:
       {
         "name": "filesystem",
         "connection_type": "stdio",
+        "is_ping_available": true,
         "stdio_config": {
           "command": "npx",
           "args": ["-y", "@anthropic/mcp-filesystem"],
@@ -234,12 +235,14 @@ Configure MCP clients in your `config.json`:
         "name": "web_search",
         "connection_type": "http",
         "connection_string": "env.WEB_SEARCH_MCP_URL",
+        "is_ping_available": false,
         "tools_to_execute": ["search", "fetch_url"]
       },
       {
         "name": "database",
         "connection_type": "sse",
         "connection_string": "https://db-mcp.example.com/sse",
+        "is_ping_available": true,
         "tools_to_execute": []
       }
     ]
@@ -273,8 +276,9 @@ func main() {
     mcpConfig := &schemas.MCPConfig{
         ClientConfigs: []schemas.MCPClientConfig{
             {
-                Name:           "filesystem",
-                ConnectionType: schemas.MCPConnectionTypeSTDIO,
+                Name:             "filesystem",
+                ConnectionType:   schemas.MCPConnectionTypeSTDIO,
+                IsPingAvailable:  true,  // Use lightweight ping for health checks
                 StdioConfig: &schemas.MCPStdioConfig{
                     Command: "npx",
                     Args:    []string{"-y", "@anthropic/mcp-filesystem"},
@@ -286,6 +290,7 @@ func main() {
                 Name:             "web_search",
                 ConnectionType:   schemas.MCPConnectionTypeHTTP,
                 ConnectionString: bifrost.Ptr("http://localhost:3001/mcp"),
+                IsPingAvailable:  false,  // Use listTools for health checks
                 ToolsToExecute:   []string{"search", "fetch_url"},
             },
         },
@@ -451,17 +456,83 @@ err = client.EditMCPClientTools("filesystem", []string{"read_file", "list_direct
 
 ## Health Monitoring
 
-Bifrost automatically monitors MCP client health:
+Bifrost automatically monitors MCP client health with periodic checks every 10 seconds by default.
 
-- **Periodic Pings**: Every 10 seconds by default
-- **Auto-Detection**: Disconnections are detected automatically
-- **State Updates**: Client state changes are reflected in API responses
+### Health Check Methods
+
+By default, Bifrost uses the lightweight **ping method** for health checks. However, you can configure the health check method based on your MCP server's capabilities:
+
+| Method | When to Use | Overhead | Fallback |
+|--------|------------|----------|----------|
+| **Ping** (default) | Server supports MCP ping protocol | Minimal | Best for most servers |
+| **ListTools** | Server doesn't support ping, or you need heavier checks | Higher | More resource-intensive |
+
+### Configuring Health Check Method
+
+You can toggle the `is_ping_available` setting for each client:
+
+#### Via Web UI
+
+1. Navigate to **MCP Gateway** and select a server
+2. In the configuration panel, toggle **"Ping Available for Health Check"**
+3. Enable: Uses lightweight ping for health checks
+4. Disable: Uses listTools method for health checks instead
+
+<Frame>
+  <img src="/media/ui-mcp-ping-available.png" alt="Ping Available Toggle" />
+</Frame>
+
+#### Via API
+
+```bash
+curl -X PUT http://localhost:8080/api/mcp/client/{id} \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "my_server",
+    "is_ping_available": false
+  }'
+```
+
+#### Via config.json
+
+```json
+{
+  "mcp": {
+    "client_configs": [
+      {
+        "name": "filesystem",
+        "connection_type": "stdio",
+        "is_ping_available": true,
+        "stdio_config": {
+          "command": "npx",
+          "args": ["-y", "@anthropic/mcp-filesystem"]
+        }
+      }
+    ]
+  }
+}
+```
+
+#### Via Go SDK
+
+```go
+err := client.EditMCPClient(context.Background(), schemas.MCPClientConfig{
+    ID:               "filesystem",
+    Name:             "filesystem",
+    IsPingAvailable:  false,  // Use listTools instead of ping
+    ToolsToExecute:   []string{"*"},
+})
+```
+
+### Health Check Behavior
 
 When a client disconnects:
 1. State changes to `disconnected`
 2. Tools from that client become unavailable
 3. You can reconnect via API or UI
 
+**Note:** Changing `is_ping_available` takes effect immediately without requiring a client reconnection.
+
 ---
 
 ## Naming Conventions

docs/media/ui-mcp-ping-available.png

@@ -38,6 +38,13 @@ MCPClientConfig:
       type: string
     is_code_mode_client:
       type: boolean
+    is_ping_available:
+      type: boolean
+      default: true
+      description: |
+        Whether the MCP server supports ping for health checks.
+        If true, uses lightweight ping method for health checks.
+        If false, uses listTools method for health checks instead.
     connection_type:
       $ref: '#/MCPConnectionType'
     connection_string: