fix: Gate notifications on capabilities (#290)

Servers may report their [tools.listChanged][] capability as false, in
which case they indicate that they will not send notifications when
available tools change.

Honor the spec by not sending notifications/tools/list_changed
notifications when capabilities.tools.listChanged is false.

[tools.listChanged]: https://modelcontextprotocol.io/specification/2025-03-26/server/tools#capabilities

Author: david-hamilton-glean

server/session.go

@@ -247,8 +247,12 @@ func (s *MCPServer) AddSessionTools(sessionID string, tools ...ServerTool) error
 
 	// It only makes sense to send tool notifications to initialized sessions --
 	// if we're not initialized yet the client can't possibly have sent their
-	// initial tools/list message
-	if session.Initialized() {
+	// initial tools/list message.
+	//
+	// For initialized sessions, honor tools.listChanged, which is specifically
+	// about whether notifications will be sent or not.
+	// see <https://modelcontextprotocol.io/specification/2025-03-26/server/tools#capabilities>
+	if session.Initialized() && s.capabilities.tools != nil && s.capabilities.tools.listChanged {
 		// Send notification only to this session
 		if err := s.SendNotificationToSpecificClient(sessionID, "notifications/tools/list_changed", nil); err != nil {
 			// Log the error but don't fail the operation
@@ -305,8 +309,12 @@ func (s *MCPServer) DeleteSessionTools(sessionID string, names ...string) error
 
 	// It only makes sense to send tool notifications to initialized sessions --
 	// if we're not initialized yet the client can't possibly have sent their
-	// initial tools/list message
-	if session.Initialized() {
+	// initial tools/list message.
+	//
+	// For initialized sessions, honor tools.listChanged, which is specifically
+	// about whether notifications will be sent or not.
+	// see <https://modelcontextprotocol.io/specification/2025-03-26/server/tools#capabilities>
+	if session.Initialized() && s.capabilities.tools != nil && s.capabilities.tools.listChanged {
 		// Send notification only to this session
 		if err := s.SendNotificationToSpecificClient(sessionID, "notifications/tools/list_changed", nil); err != nil {
 			// Log the error but don't fail the operation

server/session_test.go

@@ -858,3 +858,62 @@ func TestMCPServer_SessionToolCapabilitiesBehavior(t *testing.T) {
 		})
 	}
 }
+
+func TestMCPServer_ToolNotificationsDisabled(t *testing.T) {
+	// This test verifies that when tool capabilities are disabled, we still
+	// add/delete tools correctly but don't send notifications about it.
+	//
+	// This is important because:
+	// 1. Tools should still work even if notifications are disabled
+	// 2. We shouldn't waste resources sending notifications that won't be used
+	// 3. The client might not be ready to handle tool notifications yet
+
+	// Create a server WITHOUT tool capabilities
+	server := NewMCPServer("test-server", "1.0.0", WithToolCapabilities(false))
+	ctx := context.Background()
+
+	// Create an initialized session
+	sessionChan := make(chan mcp.JSONRPCNotification, 1)
+	session := &sessionTestClientWithTools{
+		sessionID:           "session-1",
+		notificationChannel: sessionChan,
+		initialized:         true,
+	}
+
+	// Register the session
+	err := server.RegisterSession(ctx, session)
+	require.NoError(t, err)
+
+	// Add a tool
+	err = server.AddSessionTools(session.SessionID(),
+		ServerTool{Tool: mcp.NewTool("test-tool")},
+	)
+	require.NoError(t, err)
+
+	// Verify no notification was sent
+	select {
+	case <-sessionChan:
+		t.Error("Expected no notification to be sent when capabilities.tools.listChanged is false")
+	default:
+		// This is the expected case - no notification should be sent
+	}
+
+	// Verify tool was added to session
+	assert.Len(t, session.GetSessionTools(), 1)
+	assert.Contains(t, session.GetSessionTools(), "test-tool")
+
+	// Delete the tool
+	err = server.DeleteSessionTools(session.SessionID(), "test-tool")
+	require.NoError(t, err)
+
+	// Verify no notification was sent
+	select {
+	case <-sessionChan:
+		t.Error("Expected no notification to be sent when capabilities.tools.listChanged is false")
+	default:
+		// This is the expected case - no notification should be sent
+	}
+
+	// Verify tool was deleted from session
+	assert.Len(t, session.GetSessionTools(), 0)
+}